From dc2bf2dc270c31631820e37ed6d8a916f70e62b3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 11:50:43 -0800 Subject: [PATCH 01/16] chore(quest): claim quest/m2/cut-gate/c/README.md Quest-Claim: ad1a378ac3fa2009 From 2bee67b932ddc9d70728f3e7b2b8bba70ce32414 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 12:03:23 -0800 Subject: [PATCH 02/16] wip(moq-c): session auth, server config, catalog fields, closed, largest, ready, reanchor, timebase --- rs/moq-c/src/api.rs | 209 +++++++++++++++++++++++++++++++- rs/moq-c/src/audio.rs | 43 ++++++- rs/moq-c/src/auth.rs | 259 ++++++++++++++++++++++++++++++++++++++++ rs/moq-c/src/client.rs | 87 +++++++++----- rs/moq-c/src/consume.rs | 41 +++++++ rs/moq-c/src/error.rs | 8 ++ rs/moq-c/src/lib.rs | 2 + rs/moq-c/src/publish.rs | 70 +++++++++-- rs/moq-c/src/session.rs | 19 +++ rs/moq-c/src/state.rs | 3 + rs/moq-c/src/test.rs | 85 +++++++++++++ 11 files changed, 777 insertions(+), 49 deletions(-) create mode 100644 rs/moq-c/src/auth.rs diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index d8d438b7c50..a1e12707d32 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -352,6 +352,10 @@ pub struct moq_container_init { pub init: *const u8, /// Length of `init` in bytes. pub init_len: usize, + + /// A source timebase from [moq_publish_timebase] on the same broadcast, shared with the + /// other containers given it, or 0 for an independent timestamp offset. + pub timebase: u32, } /// Validate an audio format code from C. @@ -433,6 +437,13 @@ pub struct moq_video_config { pub label_len: usize, /// Higher values are preferred; compatibility transcodes use -1 and the default is 0. pub preference: i32, + + /// Microseconds of media a decoder needs before its output is clean: after a join, decode + /// from the group start and present at the start plus this. The media consumers already + /// start this much earlier. Meaningless unless `has_warmup`. + pub warmup_us: u64, + /// Whether `warmup_us` is present; absent means none. + pub has_warmup: bool, } /// Catalog properties shared by every video rendition. @@ -494,6 +505,16 @@ pub struct moq_audio_config { pub label: *const c_char, /// Length of `label` in bytes. pub label_len: usize, + + /// The publisher's worst-case delay in microseconds between a frame being ready and its + /// flush, which floors an estimated playout delay. Meaningless unless `has_jitter`. + pub jitter_us: u64, + /// Whether `jitter_us` is present; absent means frames flush at once. + pub has_jitter: bool, + /// As [moq_video_config]'s `warmup_us`. + pub warmup_us: u64, + /// Whether `warmup_us` is present; absent means none. + pub has_warmup: bool, } /// Options for a JSON snapshot producer (lossy latest-value mode). @@ -1503,6 +1524,10 @@ pub struct moq_client_config { pub tokens: *const moq_string, /// The number of entries in `tokens`. pub tokens_len: usize, + + /// Dial once instead of redialing with backoff whenever the transport drops; the + /// transport's close then ends the session. False redials. + pub once: bool, } /// The settings [moq_session_connect] dials with when given NULL. @@ -1777,6 +1802,41 @@ pub struct moq_server_config { pub implementation: *const c_char, /// The length in bytes of `implementation`. pub implementation_len: usize, + + /// Protocol versions to accept, spelled like [moq_versions]; empty accepts every supported one. + pub versions: *const moq_string, + /// The number of entries in `versions`. + pub versions_len: usize, + + /// QUIC tuning, as in [moq_client_config]: each value applies only with its `has_*` flag, + /// and a NULL string leaves its knob at the default. + pub quic_max_streams: u64, + /// Whether `quic_max_streams` is set. + pub has_quic_max_streams: bool, + /// The QUIC idle timeout in microseconds. + pub quic_idle_timeout_us: u64, + /// Whether `quic_idle_timeout_us` is set. + pub has_quic_idle_timeout: bool, + /// The QUIC keep-alive interval in microseconds; zero derives it from the idle timeout. + pub quic_keep_alive_us: u64, + /// Whether `quic_keep_alive_us` is set. + pub has_quic_keep_alive: bool, + /// Whether to use UDP generic segmentation offload. + pub quic_gso: bool, + /// Whether `quic_gso` is set. + pub has_quic_gso: bool, + /// Whether to run path MTU discovery. + pub quic_mtu_discovery: bool, + /// Whether `quic_mtu_discovery` is set. + pub has_quic_mtu_discovery: bool, + /// The congestion controller, as in [moq_client_config], or NULL for the default. + pub quic_congestion_control: *const c_char, + /// The length in bytes of `quic_congestion_control`. + pub quic_congestion_control_len: usize, + /// A directory to write qlog traces into, or NULL for none; see [moq_qlog_supported]. + pub quic_qlog: *const c_char, + /// The length in bytes of `quic_qlog`. + pub quic_qlog_len: usize, } /// Build the listener `config` describes, binding its socket. @@ -1801,11 +1861,21 @@ unsafe fn parse_server(config: &moq_server_config) -> Result i32 { + ffi::enter(move || { + let broadcast = ffi::parse_id(broadcast)?; + State::lock().publish.timebase(broadcast) + }) +} + +/// Release a timebase handle; containers already sharing it keep their offset. +#[unsafe(no_mangle)] +pub extern "C" fn moq_publish_timebase_free(timebase: u32) -> i32 { + ffi::enter(move || { + let timebase = ffi::parse_id(timebase)?; + State::lock().publish.timebase_free(timebase) }) } @@ -3012,6 +3108,7 @@ pub unsafe extern "C" fn moq_publish_video_config(broadcast: u32, config: *const video.coded_width = (config.coded_width > 0).then_some(config.coded_width); video.coded_height = (config.coded_height > 0).then_some(config.coded_height); video.container = unsafe { parse_container(&config.container)? }; + video.warmup = config.has_warmup.then(|| std::time::Duration::from_micros(config.warmup_us)); State::lock().publish.video_config(broadcast, name, video) }) @@ -3058,6 +3155,8 @@ pub unsafe extern "C" fn moq_publish_audio_config(broadcast: u32, config: *const let description = unsafe { ffi::parse_slice(config.description, config.description_len)? }; audio.description = Some(bytes::Bytes::copy_from_slice(description)); } + audio.jitter = config.has_jitter.then(|| std::time::Duration::from_micros(config.jitter_us)); + audio.warmup = config.has_warmup.then(|| std::time::Duration::from_micros(config.warmup_us)); State::lock().publish.audio_config(broadcast, name, audio) }) @@ -3302,6 +3401,29 @@ pub extern "C" fn moq_publish_track_finish_at(track: u32, final_sequence: u64) - }) } +/// The newest content a raw track holds: its newest group, at that group's newest frame. +/// +/// `present` is false before any group was written; `frame` is 0 while the newest group is +/// empty. A publisher compares it with [moq_publish_demand_wanted]'s group to tell whether a +/// join is already served by a group it wrote. Returns zero, or a negative code on failure. +/// +/// # Safety +/// - `group`, `frame`, and `present` must point at writable values. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_publish_track_largest(track: u32, group: *mut u64, frame: *mut u64, present: *mut bool) -> i32 { + ffi::enter(move || { + let track = ffi::parse_id(track)?; + let group = unsafe { group.as_mut() }.ok_or(Error::InvalidPointer)?; + let frame = unsafe { frame.as_mut() }.ok_or(Error::InvalidPointer)?; + let present = unsafe { present.as_mut() }.ok_or(Error::InvalidPointer)?; + let largest = State::lock().publish.track_largest(track)?; + *group = largest.map_or(0, |largest| largest.group); + *frame = largest.map_or(0, |largest| largest.frame); + *present = largest.is_some(); + Ok(()) + }) +} + /// Abort a raw track with an application error code. #[unsafe(no_mangle)] pub extern "C" fn moq_publish_track_abort(track: u32, error_code: u16) -> i32 { @@ -3646,6 +3768,49 @@ pub extern "C" fn moq_publish_group_finish(group: u32) -> i32 { }) } +/// Wait until a raw group can take a frame of `size` bytes without outrunning its fastest +/// reader, for backpressure. +/// +/// `on_ready` fires exactly once: `0` once a reader holds the group and the frame fits, at +/// once while a reader has taken every frame, and once the group is finished or aborted, so +/// the next write reports why; or a negative code. Wait before each [moq_publish_group_frame] +/// and that reader paces the writer, instead of the group shedding frames it has not taken; +/// slower readers are not waited on. Writing without waiting never fails; the group sheds its +/// front instead. +/// +/// Returns zero once the wait started, or a negative code, in which case `on_ready` never fires. +/// +/// # Safety +/// - `on_ready` must be non-NULL, and `user_data` valid until it fires. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_publish_group_ready( + group: u32, + size: u64, + on_ready: ffi::moq_status_callback, + user_data: *mut c_void, +) -> i32 { + ffi::enter(move || { + let group = ffi::parse_id(group)?; + let callback = unsafe { ffi::OnStatus::new(user_data, on_ready)? }; + let group = State::lock().publish.group(group)?; + let frame = moq_net::frame::Info { size, timestamp: None }; + tokio::spawn(async move { + let res = ffi::run(async { + kio::wait(|waiter| match group.lock().as_ref() { + Some(group) => group.poll_ready(waiter, &frame), + // Finished or aborted: the next write reports why. + None => std::task::Poll::Ready(()), + }) + .await; + Ok(()) + }) + .await; + callback.call(res); + }); + Ok(()) + }) +} + /// Abort a raw group with an application error code. #[unsafe(no_mangle)] pub extern "C" fn moq_publish_group_abort(group: u32, error_code: u16) -> i32 { @@ -4251,6 +4416,38 @@ pub extern "C" fn moq_consume_read_free(read: u32) -> i32 { }) } +/// Wait until a broadcast ends: its publisher closed it, or every producer of it left. +/// +/// `on_closed` fires exactly once: `0` when the broadcast ended or [moq_consume_closed_cancel] +/// stopped the wait, or a negative error when the session driving it failed first. Release +/// `user_data` there. Returns a positive watcher handle, or a negative code on failure. +/// +/// # Safety +/// - `on_closed` must be non-NULL, and `user_data` valid until it fires. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_consume_closed( + broadcast: u32, + on_closed: ffi::moq_status_callback, + user_data: *mut c_void, +) -> i32 { + ffi::enter(move || { + let broadcast = ffi::parse_id(broadcast)?; + let on_closed = unsafe { ffi::OnStatus::new(user_data, on_closed)? }; + State::lock().consume.closed(broadcast, on_closed) + }) +} + +/// Stop a wait started by [moq_consume_closed]; its callback still fires once with `0`. +/// +/// Returns zero, or a negative code if the wait already ended. +#[unsafe(no_mangle)] +pub extern "C" fn moq_consume_closed_cancel(watcher: u32) -> i32 { + ffi::enter(move || { + let watcher = ffi::parse_id(watcher)?; + State::lock().consume.closed_cancel(watcher) + }) +} + /// Close a broadcast consumer and clean up its resources. /// /// Returns a zero on success, or a negative code on failure. diff --git a/rs/moq-c/src/audio.rs b/rs/moq-c/src/audio.rs index 776cb18a604..fe4a79a06c1 100644 --- a/rs/moq-c/src/audio.rs +++ b/rs/moq-c/src/audio.rs @@ -128,6 +128,9 @@ pub struct moq_audio_decoder_output { /// holds groups. 0 = the oldest, decoding everything cached; a live player /// sets `MOQ_DECODE_START_LATEST`. pub start: u32, + /// Hold exactly `delay.min_us` as the playout delay. False measures it from arrival + /// timing, never below `delay.min_us`, and reports it in each read's `delay_us`. + pub fixed: bool, } /// One audio frame: payload bytes plus a presentation timestamp. @@ -161,6 +164,11 @@ pub struct moq_audio_read { /// are the stopped encoder's remaining media; the first at or past it comes from a fresh /// encoder. pub end: moq_timestamp, + /// The playout delay in microseconds to hold ahead of the playhead when this read was + /// delivered: `delay.min`, or unless `fixed`, the estimate from every frame read so far. + /// The estimate measures when each read is delivered, so handle reads promptly and let + /// the playback buffer absorb the jitter, rather than pacing them to the speaker. + pub delay_us: u64, } // ---- State extensions (used internally by lib.rs) ---- @@ -188,7 +196,8 @@ impl crate::publish::Abort for AudioProducer { pub struct Audio { producers: NonZeroSlab, consumer_tasks: NonZeroSlab, - reads: NonZeroSlab>, + /// Each read with the playout delay when it was delivered. + reads: NonZeroSlab<(Read, std::time::Duration)>, } impl Audio { @@ -305,7 +314,7 @@ impl Audio { }; // Hold the lock only to buffer the read; release it before the callback. - let read_id = State::lock().audio.reads.insert(read)?; + let read_id = State::lock().audio.reads.insert((read, consumer.delay()))?; callback.call(Ok(read_id)); } } @@ -317,7 +326,7 @@ impl Audio { /// Borrow a delivered read, and a frame's samples, until its handle is freed. pub fn read_info(&self, id: Id, dst: &mut moq_audio_read) -> Result<(), Error> { - let read = self.reads.get(id).ok_or(Error::FrameNotFound)?; + let (read, delay) = self.reads.get(id).ok_or(Error::FrameNotFound)?; let (kind, gap, end) = read.info(); let frame = match read { Read::Frame(frame) => moq_audio_frame { @@ -331,7 +340,13 @@ impl Audio { data_size: 0, }, }; - *dst = moq_audio_read { kind, frame, gap, end }; + *dst = moq_audio_read { + kind, + frame, + gap, + end, + delay_us: delay.as_micros().try_into().unwrap_or(u64::MAX), + }; Ok(()) } @@ -483,6 +498,25 @@ pub unsafe extern "C" fn moq_encode_audio_frame(producer: u32, frame: *const moq }) } +/// Re-anchor an audio producer's timeline to the next frame's timestamp. +/// +/// Call this before writing after an idle gap, so the gap stays visible in the audio PTS +/// instead of being compressed out by the running sample count. +#[unsafe(no_mangle)] +pub extern "C" fn moq_encode_audio_reanchor(producer: u32) -> i32 { + ffi::enter(move || { + let producer = ffi::parse_id(producer)?; + let producer = State::lock().audio.producer(producer)?; + producer + .lock() + .as_mut() + .ok_or(Error::MediaNotFound)? + .producer + .reanchor(); + Ok(()) + }) +} + /// Flush any pending samples and finalize an audio producer. /// /// The broadcast keeps the finished track, catalog rendition included, until it closes, so a @@ -568,6 +602,7 @@ pub unsafe extern "C" fn moq_decode_audio( .transpose() .map_err(|err| Error::UnsupportedConfig(err.to_string()))?; config.delay = raw.delay.into(); + config.estimate = !raw.fixed; let on_read = unsafe { OnStatus::new(user_data, on_read)? }; diff --git a/rs/moq-c/src/auth.rs b/rs/moq-c/src/auth.rs new file mode 100644 index 00000000000..ae9883324ce --- /dev/null +++ b/rs/moq-c/src/auth.rs @@ -0,0 +1,259 @@ +//! What a session presents to its peer, and what the peer lets it do. + +use std::ffi::c_void; + +use tokio::sync::oneshot; + +use crate::ffi::{self, OnStatus}; +use crate::task::Task; +use crate::{Error, Id, NonZeroSlab, State, moq_string}; + +/// Grant snapshots and the watchers delivering them. +#[derive(Default)] +pub struct Auth { + grant: NonZeroSlab, + grants: NonZeroSlab, +} + +/// One grant delivered to a [moq_session_grants] callback, owning the strings it lends. +struct GrantRecord { + grant: Option, + /// Own the strings the views borrow; never read directly. + _publish: Vec, + _subscribe: Vec, + publish_views: Vec, + subscribe_views: Vec, +} + +// SAFETY: the views point into `publish` and `subscribe`, owned by the same record and never +// mutated after construction, so moving the record between threads keeps them valid. +unsafe impl Send for GrantRecord {} + +impl GrantRecord { + fn new(grant: Option) -> Self { + let patterns = |patterns: &moq_net::Patterns| patterns.iter().map(ToString::to_string).collect::>(); + let publish = grant.as_ref().map(|grant| patterns(&grant.publish)).unwrap_or_default(); + let subscribe = grant.as_ref().map(|grant| patterns(&grant.subscribe)).unwrap_or_default(); + let views = |strings: &[String]| { + strings + .iter() + .map(|s| moq_string { + data: s.as_ptr().cast(), + len: s.len(), + }) + .collect() + }; + Self { + publish_views: views(&publish), + subscribe_views: views(&subscribe), + grant, + _publish: publish, + _subscribe: subscribe, + } + } +} + +/// What the peer lets this side do, in this side's own paths. +/// +/// An empty pattern list grants nothing in that direction; `**` grants everything. +#[repr(C)] +pub struct moq_grant { + /// False until the peer first answers a token, and while a client reconnects; the other + /// fields are then empty. + pub present: bool, + /// The broadcast patterns this side may publish to the peer. + pub publish: *const moq_string, + /// The number of entries in `publish`. + pub publish_len: usize, + /// The broadcast patterns this side may subscribe to from the peer. + pub subscribe: *const moq_string, + /// The number of entries in `subscribe`. + pub subscribe_len: usize, + /// Microseconds until the grant lapses, measured when this was read. Meaningless unless + /// `has_expires`. + pub expires_us: u64, + /// Whether the grant lapses at all. + pub has_expires: bool, +} + +impl Auth { + fn grants(&mut self, handle: moq_net::auth::Handle, callback: OnStatus) -> Result { + let watch = handle.grant(); + self.grants.spawn( + callback, + |state| &mut state.auth.grants, + |close| Self::run_grants(callback, watch, close), + ) + } + + async fn run_grants( + callback: OnStatus, + mut watch: moq_net::auth::Watch, + mut close: oneshot::Receiver<()>, + ) -> Result<(), Error> { + let mut grant = watch.peek(); + loop { + let id = State::lock().auth.grant.insert(GrantRecord::new(grant))?; + callback.call(id); + // `biased` so a pending close always wins over a ready change. + grant = tokio::select! { + biased; + _ = &mut close => return Ok(()), + changed = kio::wait(|waiter| watch.poll_changed(waiter)) => match changed { + Ok(grant) => grant, + // Nothing will change the grant again: the session ended. + Err(_) => return Ok(()), + }, + }; + } + } + + fn grant_info(&self, id: Id, dst: &mut moq_grant) -> Result<(), Error> { + let record = self.grant.get(id).ok_or(Error::NotFound)?; + let expires = record.grant.as_ref().and_then(|grant| grant.expires); + let remaining = expires.map(|expires| expires.saturating_duration_since(moq_net::time::Instant::now())); + *dst = moq_grant { + present: record.grant.is_some(), + publish: record.publish_views.as_ptr(), + publish_len: record.publish_views.len(), + subscribe: record.subscribe_views.as_ptr(), + subscribe_len: record.subscribe_views.len(), + expires_us: remaining.map_or(0, |remaining| remaining.as_micros().try_into().unwrap_or(u64::MAX)), + has_expires: remaining.is_some(), + }; + Ok(()) + } +} + +/// Replace the tokens a dialed session presents, such as before the current ones expire. +/// +/// The first is the connection credential, unless the URL carries its own `?jwt=`; each +/// other one widens the grant over in-band AUTH. The next dial presents them, and a live +/// session that supports in-band AUTH presents them at once, withdrawing each replaced +/// token once its replacements are answered, even when one is refused. After an +/// authorization refusal the session redials only if they changed. Wait for the peer's +/// verdict with [moq_session_tokens_answered]. +/// +/// Returns zero on success, or a negative code: `MOQ_ERROR_UNSUPPORTED` for a session a +/// server accepted, which presents no tokens, and `MOQ_ERROR_INVALID_CONFIG` for an empty token. +/// +/// # Safety +/// - `tokens` must point at `tokens_len` valid [moq_string]s, or be NULL with a zero length. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_session_tokens_set(session: u32, tokens: *const moq_string, tokens_len: usize) -> i32 { + ffi::enter(move || { + let session = ffi::parse_id(session)?; + let tokens = unsafe { ffi::parse_strings(tokens, tokens_len)? } + .into_iter() + .map(|token| { + token + .try_into() + .map_err(|err: moq_net::auth::EmptyToken| Error::InvalidConfig(err.to_string())) + }) + .collect::, Error>>()?; + State::lock().session.tokens(session)?.set(tokens); + Ok(()) + }) +} + +/// Wait for the peer's first verdict on the tokens the last [moq_session_tokens_set] newly +/// presented, or on the dialed ones before any set. +/// +/// `on_answer` fires exactly once: `0` once each token is granted, in band or as a later +/// dial's connection credential, or a negative code. A refusal carries the peer's code +/// through [crate::moq_error_protocol]; `MOQ_ERROR_UNSUPPORTED` means the session cannot carry +/// an in-band token; the connection's end, including [crate::moq_session_close], is its close +/// reason. A token the set kept counts only once refused, and nothing is re-checked after the +/// answer. +/// +/// Returns zero once the wait started, or a negative code, `MOQ_ERROR_UNSUPPORTED` for a +/// session a server accepted, in which case `on_answer` never fires. +/// +/// # Safety +/// - `on_answer` must be non-NULL, and `user_data` valid until it fires. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_session_tokens_answered( + session: u32, + on_answer: ffi::moq_status_callback, + user_data: *mut c_void, +) -> i32 { + ffi::enter(move || { + let session = ffi::parse_id(session)?; + let callback = unsafe { OnStatus::new(user_data, on_answer)? }; + let tokens = State::lock().session.tokens(session)?; + tokio::spawn(async move { + let res = ffi::run(async { Ok(kio::wait(|waiter| tokens.poll_answered(waiter)).await?) }).await; + callback.call(res); + }); + Ok(()) + }) +} + +/// Follow the grant a session's peer gave it: the union of every token the session presented. +/// +/// `on_grant` fires at once with a positive grant handle for the current grant, again with a +/// new handle on every change, then exactly once more with a terminal `0` once nothing will +/// change it (the session ended, or [moq_session_grants_cancel]) or a negative error; release +/// `user_data` there. Read each handle with [moq_grant_info] and release it with +/// [moq_grant_free]. A dialed session's grant survives reconnects, reading not present while +/// offline. AUTH is only on `moq-lite-07-wip` and on moq-transport sessions that negotiate the +/// MoQ Auth extension; elsewhere the grant stays not present. +/// +/// Returns a positive watcher handle, or a negative code: `MOQ_ERROR_OFFLINE` for an accepted +/// session still in SETUP. +/// +/// # Safety +/// - `on_grant` must be non-NULL, and `user_data` valid until its terminal callback. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_session_grants( + session: u32, + on_grant: ffi::moq_status_callback, + user_data: *mut c_void, +) -> i32 { + ffi::enter(move || { + let session = ffi::parse_id(session)?; + let callback = unsafe { OnStatus::new(user_data, on_grant)? }; + let mut state = State::lock(); + let handle = state.session.auth(session)?; + state.auth.grants(handle, callback) + }) +} + +/// Stop a grant watcher from [moq_session_grants]. +/// +/// Its callback still fires once more with a terminal `0`; release `user_data` there. Grant +/// handles already delivered stay valid until freed. Returns zero, or a negative code if it +/// already ended. +#[unsafe(no_mangle)] +pub extern "C" fn moq_session_grants_cancel(watcher: u32) -> i32 { + ffi::enter(move || { + let watcher = ffi::parse_id(watcher)?; + State::lock().auth.grants.close(watcher, Error::NotFound) + }) +} + +/// Read a grant delivered to a [moq_session_grants] callback. +/// +/// The pattern strings borrow the grant handle's storage until [moq_grant_free]. +/// Returns zero on success, or a negative code on failure. +/// +/// # Safety +/// - `dst` must point at a writable [moq_grant]. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_grant_info(grant: u32, dst: *mut moq_grant) -> i32 { + ffi::enter(move || { + let grant = ffi::parse_id(grant)?; + let dst = unsafe { dst.as_mut() }.ok_or(Error::InvalidPointer)?; + State::lock().auth.grant_info(grant, dst) + }) +} + +/// Release a grant handle delivered to a [moq_session_grants] callback. +#[unsafe(no_mangle)] +pub extern "C" fn moq_grant_free(grant: u32) -> i32 { + ffi::enter(move || { + let grant = ffi::parse_id(grant)?; + State::lock().auth.grant.remove(grant).ok_or(Error::NotFound)?; + Ok(()) + }) +} diff --git a/rs/moq-c/src/client.rs b/rs/moq-c/src/client.rs index 27b37c03c1f..edd35cd2cb6 100644 --- a/rs/moq-c/src/client.rs +++ b/rs/moq-c/src/client.rs @@ -11,6 +11,49 @@ use crate::{Error, ffi, moq_client_config}; pub struct Config { pub connect: moq_tokio::connect::Config, pub quic: moq_tokio::quic::Config, + /// Dial once rather than redialing after the transport drops. + pub once: bool, +} + +/// Parse protocol version names; empty keeps the default, every supported version. +pub fn parse_versions(versions: &[String]) -> Result, Error> { + versions + .iter() + .map(|version| moq_net::Version::from_str(version).map_err(Error::InvalidConfig)) + .collect() +} + +/// The QUIC knobs a client or a server config carries, each `None` when unset. +pub struct Quic<'a> { + pub max_streams: Option, + pub idle_timeout_us: Option, + pub keep_alive_us: Option, + pub gso: Option, + pub mtu_discovery: Option, + pub congestion_control: Option<&'a str>, + pub qlog: Option<&'a str>, + pub keylog: bool, +} + +impl Quic<'_> { + pub fn parse(self) -> Result { + let micros = |us: u64| std::time::Duration::from_micros(us).into(); + let mut quic = moq_tokio::quic::Config::default(); + quic.max_streams = self.max_streams; + quic.idle_timeout = self.idle_timeout_us.map(micros); + quic.keep_alive = self.keep_alive_us.map(micros); + quic.gso = self.gso; + quic.mtu_discovery = self.mtu_discovery; + if let Some(family) = self.congestion_control { + quic.congestion_control = + Some(moq_tokio::quic::CongestionControl::from_str(family).map_err(Error::InvalidConfig)?); + } + quic.qlog = self.qlog.map(Into::into); + quic.keylog = self + .keylog + .then(|| std::env::var_os("SSLKEYLOGFILE").unwrap_or_default().into()); + Ok(quic) + } } /// What sessions opened through this library advertise in SETUP: the caller's `prefix`, @@ -59,11 +102,9 @@ pub unsafe fn parse_client(config: Option<&moq_client_config>) -> Result>()?; + out.connect.version = parse_versions(&versions)?; } + out.once = config.once; out.connect.tokens = unsafe { ffi::parse_strings(config.tokens, config.tokens_len)? } .into_iter() .map(|token| { @@ -131,31 +172,19 @@ pub unsafe fn parse_client(config: Option<&moq_client_config>) -> Result>, + + /// Watchers waiting for a broadcast to end. + closed_task: NonZeroSlab, } impl Consume { @@ -288,6 +291,33 @@ impl Consume { self.broadcast.insert(ConsumeBroadcast { broadcast, origin }) } + /// Watch for a broadcast's end, reported through the task's terminal callback. + pub fn closed(&mut self, broadcast: Id, on_closed: OnStatus) -> Result { + let ConsumeBroadcast { broadcast, origin } = + self.broadcast.get(broadcast).ok_or(Error::BroadcastNotFound)?.clone(); + let driver = origin.map(|origin| origin.driver).unwrap_or_default(); + self.closed_task.spawn( + on_closed, + |state| &mut state.consume.closed_task, + |close| async move { + driver + .watch(async move { + tokio::select! { + biased; + _ = close => {} + _ = broadcast.closed() => {} + } + Ok(()) + }) + .await + }, + ) + } + + pub fn closed_cancel(&mut self, task: Id) -> Result<(), Error> { + self.closed_task.close(task, Error::NotFound) + } + pub fn catalog(&mut self, broadcast: Id, on_catalog: OnStatus) -> Result { let ConsumeBroadcast { broadcast, origin } = self.broadcast.get(broadcast).ok_or(Error::BroadcastNotFound)?.clone(); @@ -402,6 +432,8 @@ impl Consume { .map(|label| label.as_ptr() as *const c_char) .unwrap_or(std::ptr::null()), label_len: config.label.as_ref().map_or(0, String::len), + warmup_us: micros(config.warmup), + has_warmup: config.warmup.is_some(), }; Ok(()) @@ -469,6 +501,10 @@ impl Consume { .map(|label| label.as_ptr() as *const c_char) .unwrap_or(std::ptr::null()), label_len: config.label.as_ref().map_or(0, String::len), + jitter_us: micros(config.jitter), + has_jitter: config.jitter.is_some(), + warmup_us: micros(config.warmup), + has_warmup: config.warmup.is_some(), }; Ok(()) @@ -1207,6 +1243,11 @@ impl Consume { } } +/// A catalog duration in microseconds, saturating; zero when absent. +fn micros(duration: Option) -> u64 { + duration.map_or(0, |duration| duration.as_micros().try_into().unwrap_or(u64::MAX)) +} + #[cfg(test)] mod supervision_tests { use super::*; diff --git a/rs/moq-c/src/error.rs b/rs/moq-c/src/error.rs index d37182a862d..55435dcf6fc 100644 --- a/rs/moq-c/src/error.rs +++ b/rs/moq-c/src/error.rs @@ -86,6 +86,8 @@ pub const MOQ_ERROR_UNSUPPORTED_CATALOG: i32 = -43; pub const MOQ_ERROR_UNSUPPORTED_CONFIG: i32 = -44; /// A number is outside the range the call accepts. pub const MOQ_ERROR_OUT_OF_RANGE: i32 = -45; +/// The session or peer does not support the requested operation. +pub const MOQ_ERROR_UNSUPPORTED: i32 = -46; /// Whether a protocol code is from the session or stream registry. #[repr(C)] @@ -354,6 +356,10 @@ pub enum Error { /// above what a PROBE target carries. #[error("out of range: {0}")] OutOfRange(String), + + /// The session or peer does not support the requested operation. + #[error("unsupported: {0}")] + Unsupported(String), } impl From for Error { @@ -502,6 +508,7 @@ impl ffi::ReturnCode for Error { match self { // A refused request's expiry has no session or stream code, so it gets its own status. Error::Moq(moq_net::Error::Expired) => MOQ_ERROR_EXPIRED, + Error::Moq(moq_net::Error::Unsupported) => MOQ_ERROR_UNSUPPORTED, Error::Moq(_) => MOQ_ERROR_MOQ, Error::Url(_) => MOQ_ERROR_URL, Error::Utf8(_) => MOQ_ERROR_UTF8, @@ -545,6 +552,7 @@ impl ffi::ReturnCode for Error { Error::InvalidConfig(_) => MOQ_ERROR_INVALID_CONFIG, Error::UnresolvableBroadcast(_) => MOQ_ERROR_UNRESOLVABLE_BROADCAST, Error::OutOfRange(_) => MOQ_ERROR_OUT_OF_RANGE, + Error::Unsupported(_) => MOQ_ERROR_UNSUPPORTED, } } } diff --git a/rs/moq-c/src/lib.rs b/rs/moq-c/src/lib.rs index b89a6a8f0f1..7dbbbeedb74 100644 --- a/rs/moq-c/src/lib.rs +++ b/rs/moq-c/src/lib.rs @@ -20,6 +20,7 @@ mod api; mod audio; +mod auth; mod bandwidth; mod client; mod consume; @@ -38,6 +39,7 @@ mod video; pub use api::*; pub use audio::*; +pub use auth::*; pub use bandwidth::*; pub use datagram::*; pub use decode::{moq_decode_gap, moq_decode_read_kind, moq_decode_start}; diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index f4975f26a96..54c9d400545 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -64,6 +64,9 @@ struct Broadcast { children: Children, /// Set by [`Publish::catalog_finish`]: the catalog is final, so a close leaves it alone. ended: bool, + /// Shared source timebases, owned here because each holds the catalog, so a handle that + /// outlives the broadcast cannot keep it alive. + timebases: std::collections::HashMap>, } /// A handle publishing tracks on a broadcast, by the table that holds it. @@ -317,7 +320,7 @@ pub struct Publish { datagram_demand: NonZeroSlab, /// Raw group producers, created from a raw track producer. - groups: NonZeroSlab, + groups: NonZeroSlab>, /// JSON snapshot producers (lossy latest-value tracks), each advertised in its broadcast's /// catalog for as long as it lives. @@ -342,6 +345,9 @@ pub struct Publish { /// Group requests delivered to a handler, freed on accept, abort, or free. group_request: NonZeroSlab, + + /// Shared source timebases, each naming the broadcast that owns it. + timebases: NonZeroSlab, } impl Publish { @@ -375,6 +381,7 @@ impl Publish { video: BTreeMap::new(), audio: BTreeMap::new(), ended: false, + timebases: Default::default(), })?; Ok(id) } @@ -533,15 +540,45 @@ impl Publish { self.insert_media(track, children, Some(priority)) } - pub fn container(&mut self, broadcast: Id, init: import::ContainerInit) -> Result { + /// Create a source timebase owned by `broadcast`, for containers that share one offset. + pub fn timebase(&mut self, broadcast: Id) -> Result { + let timebase = self.broadcast(broadcast)?.catalog.timebase(); + let id = self.timebases.insert(broadcast)?; + self.broadcast_mut(broadcast)?.timebases.insert(id, timebase); + Ok(id) + } + + /// Release a source timebase; containers already sharing it keep their offset. + pub fn timebase_free(&mut self, timebase: Id) -> Result<(), Error> { + let broadcast = self.timebases.remove(timebase).ok_or(Error::NotFound)?; + if let Some(broadcast) = self.broadcasts.get_mut(broadcast) { + broadcast.timebases.remove(&timebase); + } + Ok(()) + } + + /// Import a container, from `timebase` when shared, or with an independent offset. + pub fn container(&mut self, broadcast: Id, init: import::ContainerInit, timebase: Option) -> Result { + let owner = timebase + .map(|timebase| self.timebases.get(timebase).copied().ok_or(Error::NotFound)) + .transpose()?; + if owner.is_some_and(|owner| owner != broadcast) { + return Err(Error::InvalidConfig("the timebase belongs to another broadcast".into())); + } let Broadcast { producer: broadcast, catalog, driver, children, + timebases, .. } = self.broadcast(broadcast)?; - let container = import::Container::new(broadcast.clone(), catalog.reserve(), &init)?; + let reserved = match timebase { + // The owner check above means a missing entry is a broadcast that closed and was reused. + Some(timebase) => timebases.get(&timebase).ok_or(Error::NotFound)?.reserve(), + None => catalog.reserve(), + }; + let container = import::Container::new(broadcast.clone(), reserved, &init)?; let children = children.clone(); let container = Container { inner: container, @@ -1074,7 +1111,7 @@ impl Publish { pub fn group_request_accept(&mut self, request: Id) -> Result { let request = self.group_request.remove(request).ok_or(Error::NotFound)?; let group = request.fill.accept(request.sequence, None)?; - self.groups.insert(group) + self.groups.insert(crate::state::Shared::new(group)) } /// Reject a group request like [`Self::group_request_free`]; `error_code` is not delivered. @@ -1113,14 +1150,14 @@ impl Publish { pub fn track_group(&mut self, track: Id) -> Result { let raw = self.tracks.get_mut(track).ok_or(Error::TrackNotFound)?; let group = raw.inner.append_group()?; - self.groups.insert(group) + self.groups.insert(crate::state::Shared::new(group)) } /// Create a raw group with an explicit sequence number. pub fn track_group_at(&mut self, track: Id, sequence: u64) -> Result { let raw = self.tracks.get_mut(track).ok_or(Error::TrackNotFound)?; let group = raw.inner.create_group(moq_net::group::Info { sequence })?; - self.groups.insert(group) + self.groups.insert(crate::state::Shared::new(group)) } /// Write a single-frame group to a raw track, `None` when untimed. @@ -1150,6 +1187,12 @@ impl Publish { Ok(()) } + /// The newest content a raw track holds: its newest group at that group's newest frame + /// (0 while it is empty), or `None` before any group was written. + pub fn track_largest(&self, track: Id) -> Result, Error> { + Ok(self.tracks.get(track).ok_or(Error::TrackNotFound)?.inner.largest()) + } + /// Declare a raw track's exclusive final group sequence. pub fn track_finish_at(&mut self, track: Id, final_sequence: u64) -> Result<(), Error> { let raw = self.tracks.get_mut(track).ok_or(Error::TrackNotFound)?; @@ -1392,21 +1435,27 @@ impl Publish { timestamp: Option, payload: &[u8], ) -> Result<(), Error> { - let group = self.groups.get_mut(group).ok_or(Error::GroupNotFound)?; - group.write_frame(timestamp, bytes::Bytes::copy_from_slice(payload))?; + let group = self.groups.get(group).ok_or(Error::GroupNotFound)?; + let mut group = group.lock(); + group.as_mut().ok_or(Error::GroupNotFound)?.write_frame(timestamp, bytes::Bytes::copy_from_slice(payload))?; Ok(()) } + /// A raw group's producer, to wait on it without the global lock. + pub fn group(&self, group: Id) -> Result, Error> { + Ok(self.groups.get(group).ok_or(Error::GroupNotFound)?.clone()) + } + /// Finish a raw group. No more frames can be written. pub fn group_finish(&mut self, group: Id) -> Result<(), Error> { - let mut group = self.groups.remove(group).ok_or(Error::GroupNotFound)?; + let mut group = self.groups.remove(group).and_then(|group| group.take()).ok_or(Error::GroupNotFound)?; group.finish()?; Ok(()) } /// Abort a raw group with an application error code. pub fn group_abort(&mut self, group: Id, error_code: u16) -> Result<(), Error> { - let group = self.groups.remove(group).ok_or(Error::GroupNotFound)?; + let group = self.groups.remove(group).and_then(|group| group.take()).ok_or(Error::GroupNotFound)?; group.abort(moq_net::Error::App(error_code))?; Ok(()) } @@ -1630,6 +1679,7 @@ mod supervision_tests { .container( broadcast, import::ContainerInit::new(import::ContainerFormat::Ts, bytes::Bytes::new()), + None, ) .unwrap(); publish.broadcasts.remove(broadcast).unwrap(); diff --git a/rs/moq-c/src/session.rs b/rs/moq-c/src/session.rs index 1b7d744e7d5..413b53c1b26 100644 --- a/rs/moq-c/src/session.rs +++ b/rs/moq-c/src/session.rs @@ -95,6 +95,7 @@ impl Connect { .clone() .init(self.config.quic.clone()) .map_err(|err| Error::InvalidConfig(err.to_string()))?; + client = client.with_reconnect(!self.config.once); if let Some(publish) = &self.publish { client = client.with_publisher(&publish.producer); } @@ -308,6 +309,24 @@ impl Session { } } + /// The grants the session's peer gave it. A dialed session's survive reconnects. + /// + /// Errors with [`Error::Offline`] for an accepted session still in SETUP. + pub fn auth(&self, id: Id) -> Result { + match self.link(id)? { + Link::Dialed { connection, .. } => Ok(connection.auth()), + Link::Accepted(accepted) => Ok(accepted.as_ref().ok_or(Error::Offline)?.session.auth()), + } + } + + /// The tokens a dialed session presents. An accepted session presents none. + pub fn tokens(&self, id: Id) -> Result { + match self.link(id)? { + Link::Dialed { connection, .. } => Ok(connection.tokens()), + Link::Accepted(_) => Err(Error::Unsupported("a server-accepted session presents no tokens".into())), + } + } + /// Mint receive-estimate demand only when the caller asks for a consumer. pub fn recv_bandwidth(&self, id: Id) -> Result, Error> { match self.link(id)? { diff --git a/rs/moq-c/src/state.rs b/rs/moq-c/src/state.rs index ec7832ee658..2d255ed858b 100644 --- a/rs/moq-c/src/state.rs +++ b/rs/moq-c/src/state.rs @@ -1,5 +1,6 @@ use std::sync::{Arc, LazyLock, Mutex, MutexGuard, PoisonError}; +use crate::auth::Auth; use crate::bandwidth::Bandwidth; use crate::{Consume, Origin, Publish, Server, Session, audio::Audio, video::Video}; @@ -12,6 +13,7 @@ pub struct State { pub audio: Audio, pub video: Video, pub bandwidth: Bandwidth, + pub auth: Auth, } impl State { @@ -25,6 +27,7 @@ impl State { audio: Audio::default(), video: Video::default(), bandwidth: Bandwidth::default(), + auth: Auth::default(), } } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 97f72e72e86..6ad7c0b5aee 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -445,6 +445,7 @@ fn publish_container(broadcast: u32, format: moq_container_format, init: &[u8]) format: format as u32, init: init_ptr(init), init_len: init.len(), + timebase: 0, }; unsafe { moq_publish_container(broadcast, &config) } @@ -692,6 +693,10 @@ fn publish_media_labels_config_without_naming_track() { sample_rate: 0, channel_count: 0, container: moq_container::default(), + jitter_us: 0, + has_jitter: false, + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id1, 0, &mut audio_cfg) }, 0); assert_eq!( @@ -763,6 +768,8 @@ fn publish_catalog_config_invalid_broadcast() { coded_width: 0, coded_height: 0, container: moq_container::default(), + warmup_us: 0, + has_warmup: false, }; assert!(unsafe { moq_publish_video_config(0, &video) } < 0); assert!(unsafe { moq_publish_video_properties(0, &moq_video_properties::default()) } < 0); @@ -780,6 +787,10 @@ fn publish_catalog_config_invalid_broadcast() { sample_rate: 48000, channel_count: 2, container: moq_container::default(), + jitter_us: 0, + has_jitter: false, + warmup_us: 0, + has_warmup: false, }; assert!(unsafe { moq_publish_audio_config(0, &audio) } < 0); @@ -819,6 +830,8 @@ fn publish_media_owns_its_rendition_before_the_first_keyframe() { coded_width: 0, coded_height: 0, container: moq_container::default(), + warmup_us: 0, + has_warmup: false, }; assert_eq!( unsafe { moq_publish_video_config(broadcast, &video) }, @@ -870,6 +883,8 @@ fn publish_video_config_replaces_its_own_rendition() { coded_width: 640, coded_height: 360, container: moq_container::default(), + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); @@ -915,6 +930,8 @@ fn manual_video_identity_change_is_refused() { coded_height: 360, container: moq_container::default(), preference: 0, + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); let next = "vp09.00.10.08"; @@ -949,6 +966,10 @@ fn manual_audio_identity_change_is_refused() { sample_rate: 48_000, channel_count: 2, container: moq_container::default(), + jitter_us: 0, + has_jitter: false, + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_publish_audio_config(broadcast, &audio) }, 0); audio.label = label.as_ptr().cast(); @@ -1127,6 +1148,8 @@ fn publish_catalog_roundtrip() { coded_width: width, coded_height: height, container: moq_container::default(), + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); let disabled_video_name = "video-disabled"; @@ -1143,6 +1166,8 @@ fn publish_catalog_roundtrip() { coded_width: width, coded_height: height, container: moq_container::default(), + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &disabled_video) }, 0); { @@ -1183,6 +1208,10 @@ fn publish_catalog_roundtrip() { sample_rate: 48000, channel_count: 2, container: moq_container::default(), + jitter_us: 0, + has_jitter: false, + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_publish_audio_config(broadcast, &audio) }, 0); @@ -1206,6 +1235,8 @@ fn publish_catalog_roundtrip() { coded_width: 0, coded_height: 0, container: moq_container::default(), + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_consume_video_config(catalog_id, 0, &mut video_cfg) }, 0); let codec = unsafe { @@ -1275,6 +1306,10 @@ fn publish_catalog_roundtrip() { sample_rate: 0, channel_count: 0, container: moq_container::default(), + jitter_us: 0, + has_jitter: false, + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id, 0, &mut audio_cfg) }, 0); assert_eq!( @@ -1330,6 +1365,8 @@ fn a_half_specified_coded_size_round_trips() { coded_width: 1920, coded_height: 0, // absent, not "zero pixels tall" container: moq_container::default(), + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); @@ -1351,6 +1388,8 @@ fn a_half_specified_coded_size_round_trips() { coded_width: 0, coded_height: 0, container: moq_container::default(), + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_consume_video_config(catalog, 0, &mut read) }, 0); assert_eq!(read.preference, -1); @@ -1417,6 +1456,8 @@ fn raw_loc_video_uses_the_declared_catalog_container() { init: std::ptr::null(), init_len: 0, }, + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); @@ -1439,6 +1480,8 @@ fn raw_loc_video_uses_the_declared_catalog_container() { coded_width: 0, coded_height: 0, container: moq_container::default(), + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_consume_video_config(catalog, 0, &mut video_cfg) }, 0); assert_eq!( @@ -1516,6 +1559,10 @@ fn cmaf_catalog_container_carries_its_init_segment() { init: init.as_ptr(), init_len: init.len(), }, + jitter_us: 0, + has_jitter: false, + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_publish_audio_config(broadcast, &audio) }, 0); @@ -1536,6 +1583,10 @@ fn cmaf_catalog_container_carries_its_init_segment() { sample_rate: 0, channel_count: 0, container: moq_container::default(), + jitter_us: 0, + has_jitter: false, + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_consume_audio_config(catalog, 0, &mut audio_cfg) }, 0); assert_eq!( @@ -1575,6 +1626,8 @@ fn unpublishable_catalog_containers_are_rejected() { coded_width: 0, coded_height: 0, container, + warmup_us: 0, + has_warmup: false, }; // UNKNOWN only ever comes out of a catalog: we keep none of the original JSON, so @@ -3441,6 +3494,8 @@ fn media_consumers_cancel_while_subscribing() { coded_width: 0, coded_height: 0, container: moq_container::default(), + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); let (audio_name, audio_codec) = ("audio", "opus"); @@ -3456,6 +3511,10 @@ fn media_consumers_cancel_while_subscribing() { sample_rate: 48000, channel_count: 2, container: moq_container::default(), + jitter_us: 0, + has_jitter: false, + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_publish_audio_config(broadcast, &audio) }, 0); @@ -4924,6 +4983,10 @@ fn local_publish_consume() { sample_rate: 0, channel_count: 0, container: moq_container::default(), + jitter_us: 0, + has_jitter: false, + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id, 0, &mut audio_cfg) }, 0); assert_eq!(audio_cfg.sample_rate, 48000); @@ -4951,6 +5014,8 @@ fn local_publish_consume() { coded_width: 0, coded_height: 0, container: moq_container::default(), + warmup_us: 0, + has_warmup: false, }; assert!( unsafe { moq_consume_video_config(catalog_id, 0, &mut video_cfg) } < 0, @@ -5040,6 +5105,10 @@ fn follow_local() { sample_rate: 0, channel_count: 0, container: moq_container::default(), + jitter_us: 0, + has_jitter: false, + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id, 0, &mut audio_cfg) }, 0); assert_eq!(audio_cfg.sample_rate, 48000); @@ -5099,6 +5168,10 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { sample_rate: 48000, channel_count: 2, container: moq_container::default(), + jitter_us: 0, + has_jitter: false, + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_publish_audio_config(broadcast, &config) }, 0); @@ -5560,6 +5633,8 @@ fn video_publish_consume() { coded_width: 0, coded_height: 0, container: moq_container::default(), + warmup_us: 0, + has_warmup: false, }; assert_eq!( unsafe { moq_consume_video_config(catalog_id, 0, &mut video_cfg) }, @@ -5594,6 +5669,10 @@ fn video_publish_consume() { sample_rate: 0, channel_count: 0, container: moq_container::default(), + jitter_us: 0, + has_jitter: false, + warmup_us: 0, + has_warmup: false, }; assert!( unsafe { moq_consume_audio_config(catalog_id, 0, &mut audio_cfg) } < 0, @@ -5800,6 +5879,7 @@ fn audio_raw_decode_reads_the_encoder_end() { ..moq_delay::default() }, start: 0, + fixed: false, }; let read_cb = Callback::new(); id(unsafe { moq_decode_audio(catalog_id, 0, &decoded, Some(channel_callback), read_cb.ptr) }); @@ -5821,6 +5901,7 @@ fn audio_raw_decode_reads_the_encoder_end() { }, gap: moq_decode_gap::default(), end: moq_timestamp::default(), + delay_us: 0, }; assert_eq!(unsafe { moq_decode_audio_read(id(code), &mut read) }, 0); match read.kind { @@ -6699,6 +6780,10 @@ fn catalog_update_on_new_track() { sample_rate: 0, channel_count: 0, container: moq_container::default(), + jitter_us: 0, + has_jitter: false, + warmup_us: 0, + has_warmup: false, }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id1, 0, &mut audio_cfg) }, 0); assert!(unsafe { moq_consume_audio_config(catalog_id1, 1, &mut audio_cfg) } < 0); From 06facf57422a23508ecef7da6fbcf879a9899e76 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 12:04:40 -0800 Subject: [PATCH 03/16] wip(moq-c): decode video to a native surface --- rs/moq-c/c-tests/decode-output.c | 3 +- rs/moq-c/src/test.rs | 9 +++++ rs/moq-c/src/video.rs | 60 +++++++++++++++++++++++++++++--- 3 files changed, 66 insertions(+), 6 deletions(-) diff --git a/rs/moq-c/c-tests/decode-output.c b/rs/moq-c/c-tests/decode-output.c index f2c431a2a3e..18c000d69bb 100644 --- a/rs/moq-c/c-tests/decode-output.c +++ b/rs/moq-c/c-tests/decode-output.c @@ -41,7 +41,8 @@ _Static_assert(offsetof(moq_video_decoder_output, format) == 24, "format moved") _Static_assert(offsetof(moq_video_decoder_output, width) == 28, "width moved"); _Static_assert(offsetof(moq_video_decoder_output, height) == 32, "height moved"); _Static_assert(offsetof(moq_video_decoder_output, start) == 36, "start moved"); -_Static_assert(sizeof(moq_video_decoder_output) == 40, "decoder output size changed"); +_Static_assert(offsetof(moq_video_decoder_output, surface) == 40, "surface moved"); +_Static_assert(sizeof(moq_video_decoder_output) == 48, "decoder output size changed"); _Static_assert(MOQ_DECODE_READ_FRAME == 0, "frame read discriminant moved"); _Static_assert(MOQ_DECODE_READ_GAP == 1, "gap read discriminant moved"); _Static_assert(MOQ_DECODE_READ_END == 2, "end read discriminant moved"); diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 6ad7c0b5aee..41bbe585938 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -355,6 +355,7 @@ fn video_read(id: u32) -> (i32, moq_video_read) { height: 0, data: std::ptr::null(), data_size: 0, + surface: std::ptr::null(), }, gap: moq_decode_gap::default(), end: moq_timestamp::default(), @@ -5989,6 +5990,7 @@ fn video_raw_publish_consume() { width: 0, height: 0, start: 0, + surface: false, }; let frame_cb = Callback::new(); let consumer = id(unsafe { moq_decode_video(catalog_id, 0, &decoder, Some(channel_callback), frame_cb.ptr) }); @@ -6057,6 +6059,7 @@ fn video_raw_decode_output_rejected() { width: 0, height: 0, start: 0, + surface: false, }; assert_eq!( unsafe { moq_decode_video(1, 0, &bad_format, Some(ignore_callback), std::ptr::null_mut()) }, @@ -6069,6 +6072,7 @@ fn video_raw_decode_output_rejected() { width: 0, height: 0, start: moq_decode_start::MOQ_DECODE_START_LATEST as u32 + 1, + surface: false, }; assert_eq!( unsafe { moq_decode_video(1, 0, &bad_start, Some(ignore_callback), std::ptr::null_mut()) }, @@ -6082,6 +6086,7 @@ fn video_raw_decode_output_rejected() { width, height, start: 0, + surface: false, }; assert_eq!( unsafe { moq_decode_video(1, 0, &bad_size, Some(ignore_callback), std::ptr::null_mut()) }, @@ -6101,6 +6106,7 @@ fn video_raw_decode_output_rejected() { width: 160, height: 120, start: 0, + surface: false, }; assert_eq!( unsafe { moq_decode_video(u32::MAX / 2, 0, &valid, Some(ignore_callback), std::ptr::null_mut(),) }, @@ -6204,6 +6210,7 @@ fn video_raw_decode_rgba() { width: 0, height: 0, start: 0, + surface: false, }; assert_eq!(decode_first_frame(&output), (320, 240, 320 * 240 * 4)); } @@ -6221,6 +6228,7 @@ fn video_raw_decode_resize() { width: 160, height: 120, start: 0, + surface: false, }; assert_eq!(decode_first_frame(&output), (160, 120, 160 * 120 * 3 / 2)); } @@ -6631,6 +6639,7 @@ fn video_raw_decode() { width: 0, height: 0, start: 0, + surface: false, }; let frame_cb = Callback::new(); let consumer = id(unsafe { moq_decode_video(catalog_id, 0, &output, Some(channel_callback), frame_cb.ptr) }); diff --git a/rs/moq-c/src/video.rs b/rs/moq-c/src/video.rs index 2b5548bcfb4..cc56b802376 100644 --- a/rs/moq-c/src/video.rs +++ b/rs/moq-c/src/video.rs @@ -185,6 +185,11 @@ pub struct moq_video_decoder_output { /// holds groups. 0 = the oldest, decoding everything cached; a live player /// sets `MOQ_DECODE_START_LATEST`. pub start: u32, + /// Decode to the platform's own surface and hand it out as each frame's `surface`, + /// skipping the CPU conversion: `format`, `width`, and `height` are then ignored and + /// `data` is NULL. Only Apple platforms have one, an IOSurface-backed NV12 + /// `CVPixelBufferRef`; elsewhere [`moq_decode_video`] fails with `MOQ_ERROR_UNSUPPORTED`. + pub surface: bool, } /// One decoded video frame from [`moq_decode_video`]: pixels plus a @@ -209,10 +214,14 @@ pub struct moq_video_frame { pub width: u32, /// The decoded height in pixels. pub height: u32, - /// The raw frame bytes in the configured layout. + /// The raw frame bytes in the configured layout, or NULL for a `surface` decode. pub data: *const u8, /// The length in bytes of `data`. pub data_size: usize, + /// The decoder's `CVPixelBufferRef` for a `surface` decode, otherwise NULL. Borrowed: it + /// belongs to the decoder's pool, valid until the read is freed, so keep the read until + /// every GPU command reading the surface has completed. + pub surface: *const c_void, } /// One read from [`moq_decode_video`]: a decoded picture, or a break between them. @@ -479,6 +488,25 @@ impl VideoFrame { pub struct DecoderOutput { format: moq_video_pixel_format, size: Option, + /// Hand out the decoder's surface instead of converting to `format`. + surface: bool, +} + +/// Whether this platform has a surface [`moq_video_frame::surface`] can expose. +const HAS_SURFACE: bool = cfg!(any(target_os = "macos", target_os = "ios")); + +/// The `CVPixelBufferRef` a frame decoded into, or NULL when it is in CPU memory. +#[cfg(any(target_os = "macos", target_os = "ios"))] +fn surface(frame: &moq_video::Frame) -> *const c_void { + match &frame.surface { + moq_video::Surface::PixelBuffer(pixels) => std::ptr::from_ref(pixels.buffer()).cast(), + _ => std::ptr::null(), + } +} + +#[cfg(not(any(target_os = "macos", target_os = "ios")))] +fn surface(_frame: &moq_video::Frame) -> *const c_void { + std::ptr::null() } /// End a video track, given the result of draining its encoder into it. @@ -1208,13 +1236,21 @@ pub unsafe extern "C" fn moq_decode_video( let mut options = moq_video::decode::Options::new(); options.start = start; options.delay = raw.delay.into(); - // The C caller takes packed pixels, so let a backend that can decode - // straight to the CPU do that rather than downloading afterwards. - options.decoder.output = moq_video::Output::Cpu; + // A caller taking packed pixels lets a backend that can decode straight to the CPU do + // that rather than downloading afterwards. + options.decoder.output = match (raw.surface, HAS_SURFACE) { + (false, _) => moq_video::Output::Cpu, + (true, true) => moq_video::Output::Native, + (true, false) => return Err(Error::Unsupported("no decoder surface on this platform".into())), + }; // A backend with a hardware scaler (NVDEC) honors this for free; the // delivery loop still enforces it, since other backends ignore it. options.decoder.scale_hint = size; - let output = DecoderOutput { format, size }; + let output = DecoderOutput { + format, + size, + surface: raw.surface, + }; let on_read = unsafe { OnStatus::new(user_data, on_read)? }; let mut state = State::lock(); @@ -1263,6 +1299,18 @@ pub unsafe extern "C" fn moq_decode_video_read(id: u32, dst: *mut moq_video_read let read = State::lock().video.read(id)?; let (kind, gap, end) = read.info(); let frame = match &read { + Read::Frame(frame) if frame.output.surface => { + let size = frame.frame.size(); + moq_video_frame { + timestamp: frame.frame.timestamp.into(), + width: size.width, + height: size.height, + data: std::ptr::null(), + data_size: 0, + // The slab keeps the frame, and with it the surface, until the id is freed. + surface: surface(&frame.frame), + } + } Read::Frame(frame) => { let pixels = frame.pixels()?; moq_video_frame { @@ -1273,6 +1321,7 @@ pub unsafe extern "C" fn moq_decode_video_read(id: u32, dst: *mut moq_video_read // never replaced once set, so the pointer outlives this call. data: pixels.data.as_ptr(), data_size: pixels.data.len(), + surface: std::ptr::null(), } } _ => moq_video_frame { @@ -1281,6 +1330,7 @@ pub unsafe extern "C" fn moq_decode_video_read(id: u32, dst: *mut moq_video_read height: 0, data: std::ptr::null(), data_size: 0, + surface: std::ptr::null(), }, }; *dst = moq_video_read { kind, frame, gap, end }; From 541ad8d8889b3b0a9c76db515423be21bfe5a815 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 12:06:52 -0800 Subject: [PATCH 04/16] wip(moq-c): codec-only audio and video encoders --- rs/moq-c/src/encoder.rs | 444 ++++++++++++++++++++++++++++++++++++++++ rs/moq-c/src/ffi.rs | 4 +- rs/moq-c/src/lib.rs | 2 + rs/moq-c/src/state.rs | 3 + rs/moq-c/src/video.rs | 41 ++-- 5 files changed, 476 insertions(+), 18 deletions(-) create mode 100644 rs/moq-c/src/encoder.rs diff --git a/rs/moq-c/src/encoder.rs b/rs/moq-c/src/encoder.rs new file mode 100644 index 00000000000..c1b81ec95e2 --- /dev/null +++ b/rs/moq-c/src/encoder.rs @@ -0,0 +1,444 @@ +//! Codec-only encoders, independent of any broadcast. +//! +//! Each call that produces packets keeps them on the encoder handle, readable by index with +//! [moq_audio_encoder_packet] or [moq_video_encoder_packet] until the next such call or the +//! handle is freed. Publish them with [crate::moq_publish_audio] or [crate::moq_publish_video] +//! and [crate::moq_publish_media_frame]. + +use std::time::Duration; + +use bytes::Bytes; + +use crate::state::Shared; +use crate::{ + Error, NonZeroSlab, State, ffi, moq_audio_encoder_output, moq_audio_init, moq_frame, moq_timestamp, + moq_video_encoder_frame, moq_video_encoder_input, moq_video_encoder_output, moq_video_pixel_format, +}; + +/// Open codec-only encoders. Each sits behind its own lock, since encoding a frame can block +/// on the codec and must not hold the global one. +#[derive(Default)] +pub struct Encoders { + audio: NonZeroSlab>, + video: NonZeroSlab>, +} + +/// One packet the last call produced, owning what [moq_frame] borrows. +struct Packet { + payload: Bytes, + /// Boxed so the pointer handed to C survives the packet list moving. + timestamp: Option>, + keyframe: bool, +} + +impl Packet { + fn info(&self) -> moq_frame { + moq_frame { + payload: self.payload.as_ptr(), + payload_size: self.payload.len(), + timestamp: self.timestamp.as_deref().map_or(std::ptr::null(), std::ptr::from_ref), + keyframe: self.keyframe, + } + } +} + +/// Read packet `index` of the last call into `dst`. +fn packet(packets: &[Packet], index: u32, dst: &mut moq_frame) -> Result<(), Error> { + *dst = packets.get(index as usize).ok_or(Error::NoIndex)?.info(); + Ok(()) +} + +/// The packet count a call returns. +fn count(packets: &[Packet]) -> Result { + i32::try_from(packets.len()).map_err(|_| Error::OutOfRange("too many packets".into())) +} + +struct AudioEncoder { + /// `None` once finished; the packets it drained stay readable. + encoder: Option, + /// The init that publishes the packets, read once at creation. + init: Option<(crate::moq_audio_format, Bytes)>, + packets: Vec, +} + +impl AudioEncoder { + fn encoder(&mut self) -> Result<&mut moq_audio::encode::Encoder, Error> { + self.encoder + .as_mut() + .ok_or_else(|| Error::InvalidConfig("the encoder finished".into())) + } + + fn keep(&mut self, packets: impl IntoIterator) -> Result { + self.packets = packets + .into_iter() + .map(|packet| Packet { + payload: packet.payload, + timestamp: None, + keyframe: false, + }) + .collect(); + count(&self.packets) + } +} + +struct VideoEncoder { + /// `None` once finished; the packets it drained stay readable. + encoder: Option, + format: moq_video_pixel_format, + size: moq_video::Size, + packets: Vec, +} + +impl VideoEncoder { + fn encoder(&mut self) -> Result<&mut moq_video::encode::Sink, Error> { + self.encoder + .as_mut() + .ok_or_else(|| Error::InvalidConfig("the encoder finished".into())) + } + + fn keep(&mut self, packets: Vec) -> Result { + self.packets = packets + .into_iter() + .map(|packet| Packet { + payload: packet.payload, + timestamp: Some(Box::new(packet.timestamp.into())), + keyframe: packet.keyframe, + }) + .collect(); + count(&self.packets) + } +} + +/// Run `f` on an encoder resolved under the global lock, then locked on its own. +fn with( + id: u32, + slab: fn(&Encoders) -> &NonZeroSlab>, + f: impl FnOnce(&mut T) -> Result, +) -> Result { + let id = ffi::parse_id(id)?; + // A statement of its own, so the global guard drops before the encoder's lock is taken. + let shared = slab(&State::lock().encoders).get(id).cloned().ok_or(Error::NotFound)?; + let mut guard = shared.lock(); + f(guard.as_mut().ok_or(Error::NotFound)?) +} + +fn audio(encoders: &Encoders) -> &NonZeroSlab> { + &encoders.audio +} + +fn video(encoders: &Encoders) -> &NonZeroSlab> { + &encoders.video +} + +/// Open a codec-only audio encoder: interleaved f32 PCM in, codec packets out. +/// +/// `output` is read as for [crate::moq_encode_audio], except that with no input to match, a +/// zero `sample_rate` is 48000 and a zero `channels` is 2. Returns a positive encoder handle, +/// or a negative code on failure; release it with [moq_audio_encoder_free]. +/// +/// # Safety +/// - `output` must point at a readable [moq_audio_encoder_output] whose `codec` is valid. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_audio_encoder_create(output: *const moq_audio_encoder_output) -> i32 { + ffi::enter(move || { + let raw = unsafe { output.as_ref() }.ok_or(Error::InvalidPointer)?; + let codec = unsafe { ffi::parse_str(raw.codec, raw.codec_len)? }; + let codec = codec.parse().map_err(|_| Error::UnknownFormat(codec.to_string()))?; + let sample_rate = if raw.sample_rate == 0 { 48_000 } else { raw.sample_rate }; + let layout = moq_audio::Layout::from_channels(if raw.channels == 0 { 2 } else { raw.channels })?; + let input = moq_audio::encode::Input::new(sample_rate, layout); + let mut config = moq_audio::encode::Config::from_input(codec, &input); + config.bitrate = (raw.bitrate != 0).then(|| moq_net::bandwidth::Rate::from_bps(raw.bitrate.into())); + if raw.frame_duration_us != 0 { + config.frame_duration = Duration::from_micros(raw.frame_duration_us.into()); + } + + let encoder = moq_audio::encode::Encoder::new(&config)?; + let format = match encoder.codec() { + moq_audio::encode::Codec::Opus => Some(crate::moq_audio_format::MOQ_AUDIO_FORMAT_OPUS), + moq_audio::encode::Codec::Aac => Some(crate::moq_audio_format::MOQ_AUDIO_FORMAT_AAC), + _ => None, + }; + let init = format.zip(encoder.catalog().description); + State::lock().encoders.audio.insert(Shared::new(AudioEncoder { + encoder: Some(encoder), + init, + packets: Vec::new(), + })) + }) +} + +/// The interleaved samples per channel each [moq_audio_encoder_encode] call takes. +/// +/// Returns the positive count, or a negative code on failure. +#[unsafe(no_mangle)] +pub extern "C" fn moq_audio_encoder_frame_size(encoder: u32) -> i32 { + ffi::enter(move || { + with(encoder, audio, |audio| { + i32::try_from(audio.encoder()?.frame_size()).map_err(|_| Error::OutOfRange("frame size".into())) + }) + }) +} + +/// The init that publishes this encoder's packets through [crate::moq_publish_audio]: an +/// OpusHead or an AudioSpecificConfig, with `label` NULL and `hint` zeroed. +/// +/// `init` borrows the encoder's storage until [moq_audio_encoder_free]. Returns zero, or a +/// negative code: `MOQ_ERROR_UNSUPPORTED` for a codec with no init, such as PCM. +/// +/// # Safety +/// - `dst` must point at a writable [moq_audio_init]. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_audio_encoder_init(encoder: u32, dst: *mut moq_audio_init) -> i32 { + ffi::enter(move || { + let dst = unsafe { dst.as_mut() }.ok_or(Error::InvalidPointer)?; + with(encoder, audio, |audio| { + let (format, init) = audio + .init + .as_ref() + .ok_or_else(|| Error::Unsupported("this codec publishes no init".into()))?; + *dst = moq_audio_init { + format: *format as u32, + init: init.as_ptr(), + init_len: init.len(), + label: std::ptr::null(), + label_len: 0, + hint: crate::moq_audio_hint::default(), + }; + Ok(()) + }) + }) +} + +/// Retune the live encoder to `bitrate` bits per second. +#[unsafe(no_mangle)] +pub extern "C" fn moq_audio_encoder_bitrate(encoder: u32, bitrate: u64) -> i32 { + ffi::enter(move || { + with(encoder, audio, |audio| { + audio + .encoder()? + .set_bitrate(moq_net::bandwidth::Rate::from_bps(bitrate))?; + Ok(()) + }) + }) +} + +/// Encode one frame of interleaved f32 PCM, exactly [moq_audio_encoder_frame_size] samples +/// per channel. +/// +/// Returns the number of packets produced (one), read with [moq_audio_encoder_packet], or a +/// negative code on failure. +/// +/// # Safety +/// - `pcm` must point at `pcm_len` floats. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_audio_encoder_encode(encoder: u32, pcm: *const f32, pcm_len: usize) -> i32 { + ffi::enter(move || { + let pcm = unsafe { ffi::parse_slice(pcm, pcm_len)? }; + with(encoder, audio, |audio| { + let packet = audio.encoder()?.encode(pcm)?; + audio.keep([packet]) + }) + }) +} + +/// Drain the encoder, padding one final partial frame of interleaved f32 PCM (`pcm_len` may +/// be zero). +/// +/// Writes the padded samples to discard from the decoded tail into `discard_padding`, and +/// returns the number of packets drained, read with [moq_audio_encoder_packet], or a negative +/// code. Nothing more can be encoded; free the handle once the packets are read. +/// +/// # Safety +/// - `pcm` must point at `pcm_len` floats, or be NULL with a zero length. +/// - `discard_padding` must point at a writable `uint64_t`. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_audio_encoder_finish( + encoder: u32, + pcm: *const f32, + pcm_len: usize, + discard_padding: *mut u64, +) -> i32 { + ffi::enter(move || { + let pcm = unsafe { ffi::parse_slice(pcm, pcm_len)? }; + let discard_padding = unsafe { discard_padding.as_mut() }.ok_or(Error::InvalidPointer)?; + with(encoder, audio, |audio| { + let encoder = audio + .encoder + .take() + .ok_or_else(|| Error::InvalidConfig("the encoder finished".into()))?; + let finish = encoder.finish(pcm)?; + *discard_padding = finish.discard_padding() as u64; + audio.keep(finish.into_packets()) + }) + }) +} + +/// Read packet `index` from the last [moq_audio_encoder_encode] or [moq_audio_encoder_finish]. +/// +/// `payload` borrows the encoder until its next call or [moq_audio_encoder_free]; `timestamp` +/// is NULL and `keyframe` false, since the codec stamps nothing. Returns zero, or a negative +/// code, `MOQ_ERROR_NO_INDEX` past the last packet. +/// +/// # Safety +/// - `dst` must point at a writable [moq_frame]. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_audio_encoder_packet(encoder: u32, index: u32, dst: *mut moq_frame) -> i32 { + ffi::enter(move || { + let dst = unsafe { dst.as_mut() }.ok_or(Error::InvalidPointer)?; + with(encoder, audio, |audio| packet(&audio.packets, index, dst)) + }) +} + +/// Close a codec-only audio encoder and release its packets. +#[unsafe(no_mangle)] +pub extern "C" fn moq_audio_encoder_free(encoder: u32) -> i32 { + ffi::enter(move || { + let encoder = ffi::parse_id(encoder)?; + let shared = State::lock().encoders.audio.remove(encoder).ok_or(Error::NotFound)?; + // Taken outside the global lock: a call still encoding holds the encoder's own. + shared.take(); + Ok(()) + }) +} + +/// Open a codec-only video encoder: raw pictures in, access units out. +/// +/// `input` and `output` are read as for [crate::moq_encode_video], and the encoder is opened +/// here, so an unsupported codec, resolution, or backend fails now. Returns a positive encoder +/// handle, or a negative code on failure; release it with [moq_video_encoder_free]. +/// +/// # Safety +/// - `input` and `output` must point at fully populated structs, as for [crate::moq_encode_video]. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_video_encoder_create( + input: *const moq_video_encoder_input, + output: *const moq_video_encoder_output, +) -> i32 { + ffi::enter(move || { + let raw_input = unsafe { input.as_ref() }.ok_or(Error::InvalidPointer)?; + let raw_output = unsafe { output.as_ref() }.ok_or(Error::InvalidPointer)?; + let (format, config) = unsafe { crate::video::encoder_config(raw_input, raw_output)? }; + // Opened before the global lock is taken: bringing up a hardware encoder is slow. + let encoder = crate::video::block_on(moq_video::encode::Sink::open(&config))?; + State::lock().encoders.video.insert(Shared::new(VideoEncoder { + encoder: Some(encoder), + format, + size: config.size(), + packets: Vec::new(), + })) + }) +} + +/// Encode one raw picture in the input's layout and resolution. +/// +/// Returns the number of access units now available (zero or more, since a backend that +/// pipelines hands back an earlier picture's), read with [moq_video_encoder_packet], or a +/// negative code on failure. +/// +/// # Safety +/// - `frame` must point at a valid [moq_video_encoder_frame] whose `data` holds `data_size` bytes. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_video_encoder_encode(encoder: u32, frame: *const moq_video_encoder_frame) -> i32 { + ffi::enter(move || { + let frame = unsafe { frame.as_ref() }.ok_or(Error::InvalidPointer)?; + let data = unsafe { ffi::parse_slice(frame.data, frame.data_size)? }; + let timestamp = frame.timestamp.try_into()?; + with(encoder, video, |video| { + let surface = match video.format { + moq_video_pixel_format::MOQ_VIDEO_PIXEL_FORMAT_I420 => { + moq_video::Surface::I420(moq_video::I420::new(video.size, data.to_vec())?) + } + moq_video_pixel_format::MOQ_VIDEO_PIXEL_FORMAT_RGBA => moq_video::Surface::rgba(data, video.size)?, + }; + let frame = moq_video::Frame::new(surface, timestamp); + let packets = crate::video::block_on(video.encoder()?.encode(frame))?; + video.keep(packets) + }) + }) +} + +/// Force the next encoded picture to start a new group with a keyframe. +#[unsafe(no_mangle)] +pub extern "C" fn moq_video_encoder_cut(encoder: u32) -> i32 { + ffi::enter(move || { + with(encoder, video, |video| { + crate::video::block_on(video.encoder()?.cut())?; + Ok(()) + }) + }) +} + +/// Retune the live encoder to `bitrate` bits per second, from roughly the next picture. +#[unsafe(no_mangle)] +pub extern "C" fn moq_video_encoder_bitrate(encoder: u32, bitrate: u64) -> i32 { + ffi::enter(move || { + with(encoder, video, |video| { + crate::video::block_on( + video + .encoder()? + .set_bitrate(moq_net::bandwidth::Rate::from_bps(bitrate)), + )?; + Ok(()) + }) + }) +} + +/// Drain the access units the codec still holds, keeping the encoder open. +/// +/// Returns their count, read with [moq_video_encoder_packet], or a negative code. +#[unsafe(no_mangle)] +pub extern "C" fn moq_video_encoder_flush(encoder: u32) -> i32 { + ffi::enter(move || { + with(encoder, video, |video| { + let packets = crate::video::block_on(video.encoder()?.flush())?; + video.keep(packets) + }) + }) +} + +/// Drain and close the encoder. +/// +/// Returns the number of access units drained, read with [moq_video_encoder_packet], or a +/// negative code. Nothing more can be encoded; free the handle once the packets are read. +#[unsafe(no_mangle)] +pub extern "C" fn moq_video_encoder_finish(encoder: u32) -> i32 { + ffi::enter(move || { + with(encoder, video, |video| { + let encoder = video + .encoder + .take() + .ok_or_else(|| Error::InvalidConfig("the encoder finished".into()))?; + let packets = crate::video::block_on(encoder.finish())?; + video.keep(packets) + }) + }) +} + +/// Read access unit `index` from the last encode, flush, or finish. +/// +/// `payload` and `timestamp` borrow the encoder until its next call or +/// [moq_video_encoder_free]; `keyframe` says whether the unit starts from a keyframe. Returns +/// zero, or a negative code, `MOQ_ERROR_NO_INDEX` past the last unit. +/// +/// # Safety +/// - `dst` must point at a writable [moq_frame]. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_video_encoder_packet(encoder: u32, index: u32, dst: *mut moq_frame) -> i32 { + ffi::enter(move || { + let dst = unsafe { dst.as_mut() }.ok_or(Error::InvalidPointer)?; + with(encoder, video, |video| packet(&video.packets, index, dst)) + }) +} + +/// Close a codec-only video encoder and release its access units. +#[unsafe(no_mangle)] +pub extern "C" fn moq_video_encoder_free(encoder: u32) -> i32 { + ffi::enter(move || { + let encoder = ffi::parse_id(encoder)?; + let shared = State::lock().encoders.video.remove(encoder).ok_or(Error::NotFound)?; + // Taken outside the global lock: a call still encoding holds the encoder's own. + shared.take(); + Ok(()) + }) +} diff --git a/rs/moq-c/src/ffi.rs b/rs/moq-c/src/ffi.rs index b085bdf2141..d2576ce6945 100644 --- a/rs/moq-c/src/ffi.rs +++ b/rs/moq-c/src/ffi.rs @@ -548,13 +548,13 @@ pub unsafe fn parse_strings(items: *const crate::moq_string, count: usize) -> Re .collect() } -/// Parse a raw pointer and size into a byte slice. +/// Parse a raw pointer and element count into a slice. /// /// Returns an empty slice if both pointer and size are zero. /// /// # Safety /// The caller must ensure that data is valid for 'a. -pub unsafe fn parse_slice<'a>(data: *const u8, size: usize) -> Result<&'a [u8], Error> { +pub unsafe fn parse_slice<'a, T>(data: *const T, size: usize) -> Result<&'a [T], Error> { if data.is_null() { if size == 0 { return Ok(&[]); diff --git a/rs/moq-c/src/lib.rs b/rs/moq-c/src/lib.rs index 7dbbbeedb74..4b49ea5e9ef 100644 --- a/rs/moq-c/src/lib.rs +++ b/rs/moq-c/src/lib.rs @@ -26,6 +26,7 @@ mod client; mod consume; mod datagram; mod decode; +mod encoder; mod error; mod ffi; mod id; @@ -42,6 +43,7 @@ pub use audio::*; pub use auth::*; pub use bandwidth::*; pub use datagram::*; +pub use encoder::*; pub use decode::{moq_decode_gap, moq_decode_read_kind, moq_decode_start}; pub use error::*; pub use ffi::{moq_follow_callback, moq_state_callback, moq_status_callback}; diff --git a/rs/moq-c/src/state.rs b/rs/moq-c/src/state.rs index 2d255ed858b..da81ad6d76b 100644 --- a/rs/moq-c/src/state.rs +++ b/rs/moq-c/src/state.rs @@ -1,6 +1,7 @@ use std::sync::{Arc, LazyLock, Mutex, MutexGuard, PoisonError}; use crate::auth::Auth; +use crate::encoder::Encoders; use crate::bandwidth::Bandwidth; use crate::{Consume, Origin, Publish, Server, Session, audio::Audio, video::Video}; @@ -14,6 +15,7 @@ pub struct State { pub video: Video, pub bandwidth: Bandwidth, pub auth: Auth, + pub encoders: Encoders, } impl State { @@ -28,6 +30,7 @@ impl State { video: Video::default(), bandwidth: Bandwidth::default(), auth: Auth::default(), + encoders: Encoders::default(), } } diff --git a/rs/moq-c/src/video.rs b/rs/moq-c/src/video.rs index cc56b802376..c317c2ffb9b 100644 --- a/rs/moq-c/src/video.rs +++ b/rs/moq-c/src/video.rs @@ -261,7 +261,7 @@ pub struct Video { /// /// `pollster` rather than a tokio helper because those panic when the calling /// thread is driving a runtime, which the one dispatching a callback is. -fn block_on(future: impl std::future::Future) -> T { +pub(crate) fn block_on(future: impl std::future::Future) -> T { pollster::block_on(future) } @@ -957,6 +957,29 @@ unsafe fn encoder_kind(output: &moq_video_encoder_output) -> Result Result<(moq_video_pixel_format, moq_video::encode::Config), Error> { + let format = pixel_format_from_u32(input.format)?; + let framerate = moq_video::FrameRate::new(input.framerate.numerator, input.framerate.denominator) + .map_err(|err| Error::InvalidConfig(format!("invalid framerate: {err}")))?; + let mut config = moq_video::encode::Config::new(input.width, input.height, framerate); + config.codec = codec_from_u32(output.codec)?; + config.kind = unsafe { encoder_kind(output)? }; + // The C ABI spells an unset knob as 0, which neither field accepts as a real + // value: a zero bitrate or GOP is the default, not a request. + config.bitrate = (output.bitrate != 0).then(|| moq_net::bandwidth::Rate::from_bps(output.bitrate)); + if output.gop != 0 { + config.gop = moq_video::encode::Gop::Keyframe { interval: output.gop }; + } + Ok((format, config)) +} + /// Open a video track on a broadcast, encoding the raw frames you publish to it. /// /// The encoder is opened here, so an unsupported codec, resolution, or backend @@ -992,21 +1015,7 @@ pub unsafe extern "C" fn moq_encode_video( )); } - let format = pixel_format_from_u32(raw_input.format)?; - - let framerate = moq_video::FrameRate::new(raw_input.framerate.numerator, raw_input.framerate.denominator) - .map_err(|err| Error::InvalidConfig(format!("invalid framerate: {err}")))?; - let mut config = moq_video::encode::Config::new(raw_input.width, raw_input.height, framerate); - config.codec = codec_from_u32(raw_output.codec)?; - config.kind = unsafe { encoder_kind(raw_output)? }; - // The C ABI spells an unset knob as 0, which neither field accepts as a real - // value: a zero bitrate or GOP is the default, not a request. - config.bitrate = (raw_output.bitrate != 0).then(|| moq_net::bandwidth::Rate::from_bps(raw_output.bitrate)); - if raw_output.gop != 0 { - config.gop = moq_video::encode::Gop::Keyframe { - interval: raw_output.gop, - }; - } + let (format, config) = unsafe { encoder_config(raw_input, raw_output)? }; // Both before the global lock is taken: bringing up a hardware encoder is slow // enough that every other call would wait behind it. The probe runs first and From ccdbbe69756b731c6f60af0929a266872a5a68a8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 12:28:45 -0800 Subject: [PATCH 05/16] wip(moq-c): socket endpoints, group-ready wake on end, parity tests Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/api.rs | 14 +- rs/moq-c/src/consume.rs | 101 +++++-- rs/moq-c/src/lib.rs | 2 + rs/moq-c/src/publish.rs | 71 ++++- rs/moq-c/src/socket.rs | 556 ++++++++++++++++++++++++++++++++++++ rs/moq-c/src/state.rs | 3 + rs/moq-c/src/test.rs | 17 +- rs/moq-c/src/test/parity.rs | 495 ++++++++++++++++++++++++++++++++ 8 files changed, 1214 insertions(+), 45 deletions(-) create mode 100644 rs/moq-c/src/socket.rs create mode 100644 rs/moq-c/src/test/parity.rs diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index a1e12707d32..08d64840783 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -1843,7 +1843,7 @@ pub struct moq_server_config { /// /// # Safety /// - Every non-NULL pointer in `config` must be valid for its length. -unsafe fn parse_server(config: &moq_server_config) -> Result { +pub(crate) unsafe fn parse_server(config: &moq_server_config) -> Result { let mut listen = moq_tokio::listen::Config::default(); let prefix = unsafe { ffi::parse_str_optional(config.implementation, config.implementation_len)? }; listen.implementation = Some(crate::client::implementation(prefix)?); @@ -3792,16 +3792,20 @@ pub unsafe extern "C" fn moq_publish_group_ready( ffi::enter(move || { let group = ffi::parse_id(group)?; let callback = unsafe { ffi::OnStatus::new(user_data, on_ready)? }; - let group = State::lock().publish.group(group)?; + let (group, mut ended) = State::lock().publish.group(group)?; let frame = moq_net::frame::Info { size, timestamp: None }; tokio::spawn(async move { let res = ffi::run(async { - kio::wait(|waiter| match group.lock().as_ref() { + let ready = kio::wait(|waiter| match group.lock().as_ref() { Some(group) => group.poll_ready(waiter, &frame), // Finished or aborted: the next write reports why. None => std::task::Poll::Ready(()), - }) - .await; + }); + // The handle ending also resolves it: a finish does not wake `poll_ready`. + tokio::select! { + () = ready => {} + _ = ended.changed() => {} + } Ok(()) }) .await; diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index 2bab14d22e1..2ed5857526d 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -162,6 +162,8 @@ enum RawControl { Pending(Option), /// Subscribed: updates apply at once, so a refusal reaches the caller. Live(moq_net::track::Control), + /// A socket's `tcp` half: one group, with no subscription to update. + Group, } /// Outcome of polling a raw track source alongside its control channels. @@ -806,31 +808,83 @@ impl Consume { RawStep::End | RawStep::Stop => return Ok(()), }; - loop { - let frame = match moq_net::kio::wait(|waiter| -> Poll, Error>> { - if Pin::new(&mut close).poll(&mut waiter.context()).is_ready() { - return Poll::Ready(Ok(RawStep::Stop)); - } - match ready!(group.poll_read_frame(waiter))? { - Some(frame) => Poll::Ready(Ok(RawStep::Item(frame))), - None => Poll::Ready(Ok(RawStep::End)), + if Self::run_group(callback, &mut group, &mut close).await? { + return Ok(()); + } + } + } + + /// Deliver every frame of `group` in order, returning whether `close` fired. + /// + /// `close` is a oneshot that panics if polled after completion, so a `true` must unwind + /// the whole task. + async fn run_group( + callback: OnStatus, + group: &mut moq_net::group::Consumer, + close: &mut oneshot::Receiver<()>, + ) -> Result { + loop { + let frame = match moq_net::kio::wait(|waiter| -> Poll, Error>> { + if Pin::new(&mut *close).poll(&mut waiter.context()).is_ready() { + return Poll::Ready(Ok(RawStep::Stop)); + } + match ready!(group.poll_read_frame(waiter))? { + Some(frame) => Poll::Ready(Ok(RawStep::Item(frame))), + None => Poll::Ready(Ok(RawStep::End)), + } + }) + .await? + { + RawStep::Item(frame) => frame, + // Group fully read. + RawStep::End => return Ok(false), + // Consumer closed mid-group: terminate without touching `close` again. + RawStep::Stop => return Ok(true), + }; + + // Hold the lock only to buffer the read; release it before the callback. + let frame = Timed::new(frame.payload, frame.timestamp); + let frame_id = State::lock().consume.raw_frame.insert(frame)?; + callback.call(Ok(frame_id)); + } + } + + /// Read a socket stream's peer half as a raw track reader: `track` for a `track` session, + /// or the one group of a `tcp` session. + /// + /// The `track` half keeps the reliable, oldest-first subscription the socket opened it with + /// until [`Self::raw_track_update`] changes it. + pub(crate) fn socket_read( + &mut self, + half: crate::socket::Half, + driver: crate::ffi::Background, + on_frame: OnStatus, + ) -> Result { + let (task, mut close) = Task::new(on_frame); + let control = match &half { + crate::socket::Half::Track(track) => RawControl::Live(track.control()), + crate::socket::Half::Group(_) => RawControl::Group, + }; + let id = self.raw_task.insert(RawTaskEntry { task, control })?; + + tokio::spawn(async move { + let res = crate::ffi::run(driver.watch(async move { + match half { + crate::socket::Half::Track(track) => Self::run_raw(on_frame, track.ordered(), close).await, + crate::socket::Half::Group(mut group) => { + Self::run_group(on_frame, &mut group, &mut close).await.map(drop) } - }) - .await? - { - RawStep::Item(frame) => frame, - // Group fully read: advance to the next group. - RawStep::End => break, - // Consumer closed mid-group: terminate without touching `close` again. - RawStep::Stop => return Ok(()), - }; + } + })) + .await; - // Hold the lock only to buffer the read; release it before the callback. - let frame = Timed::new(frame.payload, frame.timestamp); - let frame_id = State::lock().consume.raw_frame.insert(frame)?; - callback.call(Ok(frame_id)); + let entry = State::lock().consume.raw_task.remove(id); + if let Some(entry) = entry { + entry.task.callback.call(res); } - } + }); + + Ok(id) } pub fn raw_track_update( @@ -843,6 +897,9 @@ impl Consume { match &mut entry.control { RawControl::Pending(pending) => *pending = Some(subscription), RawControl::Live(control) => Self::update_raw(control, subscription)?, + RawControl::Group => { + return Err(Error::Unsupported("a tcp socket stream has no subscription".into())); + } } Ok(()) } diff --git a/rs/moq-c/src/lib.rs b/rs/moq-c/src/lib.rs index 4b49ea5e9ef..e0c3936a353 100644 --- a/rs/moq-c/src/lib.rs +++ b/rs/moq-c/src/lib.rs @@ -34,6 +34,7 @@ mod origin; mod publish; mod server; mod session; +mod socket; mod state; mod task; mod video; @@ -48,6 +49,7 @@ pub use decode::{moq_decode_gap, moq_decode_read_kind, moq_decode_start}; pub use error::*; pub use ffi::{moq_follow_callback, moq_state_callback, moq_status_callback}; pub use id::*; +pub use socket::*; pub use video::*; pub(crate) use client::*; diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 54c9d400545..97358f73d6f 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -120,7 +120,7 @@ impl Default for Children { } impl Children { - fn new() -> Self { + pub(crate) fn new() -> Self { Self(Arc::new(std::sync::Mutex::new(Family::Open { open: HashSet::new(), kept: Vec::new(), @@ -170,7 +170,7 @@ impl Children { } /// Refuse new children, handing back the open ones and letting go of the finished ones. - fn close(&self) -> HashSet { + pub(crate) fn close(&self) -> HashSet { let family = std::mem::replace(&mut *self.lock(), Family::Closed); match family { Family::Open { open, .. } => open, @@ -187,6 +187,14 @@ pub struct Target<'a> { pub children: &'a Children, } +/// A raw group handle. +struct GroupEntry { + inner: crate::state::Shared, + /// Dropped with the entry, ending a [crate::moq_publish_group_ready] wait that finishing the + /// group would not wake: a finished group no reader holds never turns ready on its own. + ended: tokio::sync::watch::Sender<()>, +} + /// A producer handle, with the broadcast that keeps it once finished. struct Kept { inner: T, @@ -320,7 +328,7 @@ pub struct Publish { datagram_demand: NonZeroSlab, /// Raw group producers, created from a raw track producer. - groups: NonZeroSlab>, + groups: NonZeroSlab, /// JSON snapshot producers (lossy latest-value tracks), each advertised in its broadcast's /// catalog for as long as it lives. @@ -1111,7 +1119,7 @@ impl Publish { pub fn group_request_accept(&mut self, request: Id) -> Result { let request = self.group_request.remove(request).ok_or(Error::NotFound)?; let group = request.fill.accept(request.sequence, None)?; - self.groups.insert(crate::state::Shared::new(group)) + self.insert_group(group) } /// Reject a group request like [`Self::group_request_free`]; `error_code` is not delivered. @@ -1146,18 +1154,45 @@ impl Publish { children.insert(&mut self.tracks, raw, Child::Track) } + /// Hand a socket stream's `track` half to C as a raw track handle, a child of the + /// endpoint's `children` like a track is of its broadcast. + pub(crate) fn socket_track(&mut self, track: moq_net::track::Producer, children: &Children) -> Result { + let raw = Kept { + inner: track, + children: children.clone(), + }; + children.insert(&mut self.tracks, raw, Child::Track) + } + + /// Hand a socket stream's `tcp` half to C as a group handle. + pub(crate) fn socket_group(&mut self, group: moq_net::group::Producer) -> Result { + self.insert_group(group) + } + + /// End a closed endpoint's open `track` halves, as a broadcast's close ends its tracks, + /// and let go of its finished ones. + pub(crate) fn socket_close(&mut self, children: &Children) { + for child in children.close() { + if let Child::Track(id) = child + && let Some(track) = self.tracks.remove(id) + { + track.abort(moq_net::Error::Unroutable); + } + } + } + /// Append a new group to a raw track, returning a group producer. pub fn track_group(&mut self, track: Id) -> Result { let raw = self.tracks.get_mut(track).ok_or(Error::TrackNotFound)?; let group = raw.inner.append_group()?; - self.groups.insert(crate::state::Shared::new(group)) + self.insert_group(group) } /// Create a raw group with an explicit sequence number. pub fn track_group_at(&mut self, track: Id, sequence: u64) -> Result { let raw = self.tracks.get_mut(track).ok_or(Error::TrackNotFound)?; let group = raw.inner.create_group(moq_net::group::Info { sequence })?; - self.groups.insert(crate::state::Shared::new(group)) + self.insert_group(group) } /// Write a single-frame group to a raw track, `None` when untimed. @@ -1436,26 +1471,38 @@ impl Publish { payload: &[u8], ) -> Result<(), Error> { let group = self.groups.get(group).ok_or(Error::GroupNotFound)?; - let mut group = group.lock(); + let mut group = group.inner.lock(); group.as_mut().ok_or(Error::GroupNotFound)?.write_frame(timestamp, bytes::Bytes::copy_from_slice(payload))?; Ok(()) } - /// A raw group's producer, to wait on it without the global lock. - pub fn group(&self, group: Id) -> Result, Error> { - Ok(self.groups.get(group).ok_or(Error::GroupNotFound)?.clone()) + fn insert_group(&mut self, group: moq_net::group::Producer) -> Result { + self.groups.insert(GroupEntry { + inner: crate::state::Shared::new(group), + ended: tokio::sync::watch::Sender::new(()), + }) + } + + /// A raw group's producer, to wait on it without the global lock, and a receiver whose + /// `changed` fails once the handle ends. + pub fn group( + &self, + group: Id, + ) -> Result<(crate::state::Shared, tokio::sync::watch::Receiver<()>), Error> { + let entry = self.groups.get(group).ok_or(Error::GroupNotFound)?; + Ok((entry.inner.clone(), entry.ended.subscribe())) } /// Finish a raw group. No more frames can be written. pub fn group_finish(&mut self, group: Id) -> Result<(), Error> { - let mut group = self.groups.remove(group).and_then(|group| group.take()).ok_or(Error::GroupNotFound)?; + let mut group = self.groups.remove(group).and_then(|group| group.inner.take()).ok_or(Error::GroupNotFound)?; group.finish()?; Ok(()) } /// Abort a raw group with an application error code. pub fn group_abort(&mut self, group: Id, error_code: u16) -> Result<(), Error> { - let group = self.groups.remove(group).and_then(|group| group.take()).ok_or(Error::GroupNotFound)?; + let group = self.groups.remove(group).and_then(|group| group.inner.take()).ok_or(Error::GroupNotFound)?; group.abort(moq_net::Error::App(error_code))?; Ok(()) } diff --git a/rs/moq-c/src/socket.rs b/rs/moq-c/src/socket.rs new file mode 100644 index 00000000000..6eafcd697b1 --- /dev/null +++ b/rs/moq-c/src/socket.rs @@ -0,0 +1,556 @@ +//! Socket endpoints: two-way sessions between endpoints sharing an origin. +//! +//! A `tcp` session's halves are each one group: write with [crate::moq_publish_group_frame] and +//! read frames in order. A `track` session's halves are each a whole track: write with +//! [crate::moq_publish_track_group] and read it like [crate::moq_consume_track]. + +use std::ffi::{c_char, c_void}; +use std::sync::Arc; + +use moq_net::socket::{Endpoint, Incoming, TcpStream, TrackStream}; +use tokio::sync::oneshot; + +use crate::ffi::{self, Background, OnStatus}; +use crate::publish::Children; +use crate::task::Task; +use crate::{Error, Id, NonZeroSlab, State, moq_string, moq_track_info}; + +/// Socket endpoints and the sessions they dial or accept. +#[derive(Default)] +pub struct Socket { + endpoints: NonZeroSlab, + /// Dials, accept loops and accepts in progress. + tasks: NonZeroSlab, + incoming: NonZeroSlab, + streams: NonZeroSlab, +} + +struct EndpointEntry { + inner: Arc, + driver: Background, + /// The endpoint's `track` halves handed to C, ended when it closes. + children: Children, +} + +enum IncomingKind { + Tcp(Incoming), + Track(Incoming), +} + +struct IncomingEntry { + inner: IncomingKind, + peer: String, + session: String, + driver: Background, + children: Children, +} + +/// The peer's half of a stream, read through [Consume](crate::Consume). +pub(crate) enum Half { + Track(moq_net::track::Subscriber), + Group(moq_net::group::Consumer), +} + +/// This side's half of a stream, until C takes it. +enum Writer { + Track(moq_net::track::Producer), + Group(moq_net::group::Producer), +} + +struct StreamEntry { + peer: String, + session: String, + writer: Option, + reader: Option, + driver: Background, + children: Children, +} + +impl StreamEntry { + fn tcp(stream: TcpStream, driver: Background, children: Children) -> Self { + let (peer, session) = (stream.peer().to_string(), stream.session().to_string()); + Self { + peer, + session, + writer: Some(Writer::Group(stream.producer)), + reader: Some(Half::Group(stream.consumer)), + driver, + children, + } + } + + fn track(stream: TrackStream, driver: Background, children: Children) -> Self { + let (peer, session) = (stream.peer().to_string(), stream.session().to_string()); + Self { + peer, + session, + writer: Some(Writer::Track(stream.producer)), + reader: Some(Half::Track(stream.consumer)), + driver, + children, + } + } +} + +/// Deliver `id` and end, or end without one when `close` fires first. +async fn deliver( + callback: OnStatus, + close: oneshot::Receiver<()>, + pending: impl Future>, +) -> Result<(), Error> { + // `biased` so a pending close always wins over a ready stream. + let stream = tokio::select! { + biased; + _ = close => return Ok(()), + res = pending => res?, + }; + let id = State::lock().socket.streams.insert(stream)?; + callback.call(Ok(id)); + Ok(()) +} + +impl Socket { + fn endpoint(&self, id: Id) -> Result<&EndpointEntry, Error> { + let endpoint = self.endpoints.get(id).ok_or(Error::NotFound)?; + endpoint.driver.check()?; + Ok(endpoint) + } + + fn create(&mut self, origin: &crate::origin::Producer, prefix: &str, id: &str) -> Result { + let inner = Endpoint::new(origin, prefix, id)?; + self.endpoints.insert(EndpointEntry { + inner: Arc::new(inner), + driver: origin.driver.clone(), + children: Children::new(), + }) + } + + fn dial(&mut self, endpoint: Id, peer: &str, track: Option>, callback: OnStatus) -> Result { + let EndpointEntry { inner, driver, children } = self.endpoint(endpoint)?; + let (driver, children) = (driver.clone(), children.clone()); + let watch = driver.clone(); + let pending: std::pin::Pin> + Send>> = match track { + None => { + let dialing = inner.dial_tcp(peer)?; + Box::pin(async move { Ok(StreamEntry::tcp(dialing.await?, driver, children)) }) + } + Some(info) => { + let dialing = inner.dial_track(peer, info)?; + Box::pin(async move { Ok(StreamEntry::track(dialing.await?, driver, children)) }) + } + }; + self.tasks.spawn( + callback, + |state| &mut state.socket.tasks, + |close| async move { watch.watch(deliver(callback, close, pending)).await }, + ) + } + + fn accept(&mut self, endpoint: Id, track: bool, callback: OnStatus) -> Result { + let EndpointEntry { inner, driver, children } = self.endpoint(endpoint)?; + let (inner, driver, children) = (inner.clone(), driver.clone(), children.clone()); + let poll = move |waiter: &kio::Waiter| match track { + false => inner.poll_accept_tcp(waiter).map_ok(IncomingKind::Tcp), + true => inner.poll_accept_track(waiter).map_ok(IncomingKind::Track), + }; + // The first poll starts listening, so poll once before returning: a dial sent after + // this call then queues for the loop instead of finding nobody listening. + let mut first = match poll(&kio::Waiter::noop()) { + std::task::Poll::Ready(Err(err)) if !matches!(err, moq_net::Error::Closed) => return Err(err.into()), + std::task::Poll::Ready(res) => Some(res), + std::task::Poll::Pending => None, + }; + self.tasks.spawn( + callback, + |state| &mut state.socket.tasks, + |mut close| async move { + let watch = driver.clone(); + let run = async move { + loop { + let next = match first.take() { + Some(res) => res, + // `biased` so a pending close always wins over a ready dial. + None => tokio::select! { + biased; + _ = &mut close => return Ok(()), + res = kio::wait(&poll) => res, + }, + }; + let incoming = match next { + Ok(incoming) => incoming, + // The endpoint closed: no more dials will arrive. + Err(moq_net::Error::Closed) => return Ok(()), + Err(err) => return Err(err.into()), + }; + let (peer, session) = match &incoming { + IncomingKind::Tcp(incoming) => (incoming.peer(), incoming.session()), + IncomingKind::Track(incoming) => (incoming.peer(), incoming.session()), + }; + let entry = IncomingEntry { + peer: peer.to_string(), + session: session.to_string(), + inner: incoming, + driver: driver.clone(), + children: children.clone(), + }; + let id = State::lock().socket.incoming.insert(entry)?; + callback.call(Ok(id)); + } + }; + watch.watch(run).await + }, + ) + } + + fn incoming_accept(&mut self, incoming: Id, info: Option, callback: OnStatus) -> Result { + let entry = self.incoming.get(incoming).ok_or(Error::NotFound)?; + entry.driver.check()?; + if info.is_some() && matches!(entry.inner, IncomingKind::Tcp(_)) { + return Err(Error::InvalidConfig("a tcp session has no track info".into())); + } + let IncomingEntry { + inner, driver, children, .. + } = self.incoming.remove(incoming).ok_or(Error::NotFound)?; + let watch = driver.clone(); + let pending: std::pin::Pin> + Send>> = match inner { + IncomingKind::Tcp(incoming) => { + let accepting = incoming.accept(); + Box::pin(async move { Ok(StreamEntry::tcp(accepting.await?, driver, children)) }) + } + IncomingKind::Track(incoming) => { + let accepting = incoming.accept(info); + Box::pin(async move { Ok(StreamEntry::track(accepting.await?, driver, children)) }) + } + }; + self.tasks.spawn( + callback, + |state| &mut state.socket.tasks, + |close| async move { watch.watch(deliver(callback, close, pending)).await }, + ) + } + + fn incoming_info(&self, incoming: Id, peer: Option<&mut moq_string>, session: Option<&mut moq_string>) -> Result<(), Error> { + let entry = self.incoming.get(incoming).ok_or(Error::NotFound)?; + write_ids(&entry.peer, &entry.session, peer, session); + Ok(()) + } + + fn stream_info(&self, stream: Id, peer: Option<&mut moq_string>, session: Option<&mut moq_string>) -> Result<(), Error> { + let entry = self.streams.get(stream).ok_or(Error::NotFound)?; + write_ids(&entry.peer, &entry.session, peer, session); + Ok(()) + } +} + +fn write_ids(peer: &str, session: &str, peer_dst: Option<&mut moq_string>, session_dst: Option<&mut moq_string>) { + let view = |s: &str| moq_string { + data: s.as_ptr().cast::(), + len: s.len(), + }; + if let Some(dst) = peer_dst { + *dst = view(peer); + } + if let Some(dst) = session_dst { + *dst = view(session); + } +} + +/// Open a socket endpoint named `id` under `prefix` on an origin, announcing it to the peers +/// reachable through that origin. +/// +/// `id` names the endpoint: a well-known name for a server, or a random one for a client. It +/// must be one path segment. Peers find each other under the same `prefix`, so connect the +/// origin to a session (or share it locally) before dialing. Close it with [moq_socket_close]. +/// +/// Returns a positive endpoint handle, or a negative code, such as when the origin may not +/// publish `/.socket/`. +/// +/// # Safety +/// - `prefix` must point at `prefix_len` bytes, and `id` at `id_len` bytes. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_socket_create( + origin: u32, + prefix: *const c_char, + prefix_len: usize, + id: *const c_char, + id_len: usize, +) -> i32 { + ffi::enter(move || { + let origin = ffi::parse_id(origin)?; + let prefix = unsafe { ffi::parse_str(prefix, prefix_len)? }; + let id = unsafe { ffi::parse_str(id, id_len)? }; + let mut state = State::lock(); + let origin = state.origin.get(origin)?.clone(); + state.socket.create(&origin, prefix, id) + }) +} + +/// Close a socket endpoint and release its handle. +/// +/// Withdraws the endpoint, ends its accept loops with a terminal `0`, fails its pending dials +/// and accepts, and resets its open sessions, aborting each `track` half still open. Handles +/// already delivered stay valid until released. +/// +/// Returns zero, or a negative code if the endpoint is unknown. +#[unsafe(no_mangle)] +pub extern "C" fn moq_socket_close(endpoint: u32) -> i32 { + ffi::enter(move || { + let endpoint = ffi::parse_id(endpoint)?; + let mut state = State::lock(); + let entry = state.socket.endpoints.remove(endpoint).ok_or(Error::NotFound)?; + entry.inner.close(); + state.publish.socket_close(&entry.children); + Ok(()) + }) +} + +/// Dial the endpoint `peer` in a new `tcp` session: one ordered, reliable byte-message stream +/// each way. +/// +/// Waits for as long as the peer takes to accept, including for its endpoint to be announced. +/// `on_stream` fires with a positive stream handle once the peer accepts, then exactly once +/// more with a terminal code: `0` (including after [moq_socket_cancel], which gives up and +/// resets the session) or a negative error, `MOQ_ERROR_NOT_FOUND` when the peer rejects it +/// and `MOQ_ERROR_UNSUPPORTED` for a dial to this endpoint itself or across a hop that cannot +/// carry it. Release `user_data` at the terminal callback. +/// +/// Returns a positive task handle, or a negative code. +/// +/// # Safety +/// - `peer` must point at `peer_len` bytes. +/// - `on_stream` must be non-NULL, and `user_data` valid until its terminal callback. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_socket_dial_tcp( + endpoint: u32, + peer: *const c_char, + peer_len: usize, + on_stream: ffi::moq_status_callback, + user_data: *mut c_void, +) -> i32 { + ffi::enter(move || { + let endpoint = ffi::parse_id(endpoint)?; + let peer = unsafe { ffi::parse_str(peer, peer_len)? }; + let callback = unsafe { OnStatus::new(user_data, on_stream)? }; + State::lock().socket.dial(endpoint, peer, None, callback) + }) +} + +/// Dial the endpoint `peer` in a new `track` session, whose halves are whole tracks; see +/// [moq_socket_dial_tcp]. +/// +/// `info` describes this side's half, or NULL to keep every message until read, with no +/// max age. +/// +/// # Safety +/// - `peer` must point at `peer_len` bytes, and `info` be NULL or point at a [moq_track_info]. +/// - `on_stream` must be non-NULL, and `user_data` valid until its terminal callback. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_socket_dial_track( + endpoint: u32, + peer: *const c_char, + peer_len: usize, + info: *const moq_track_info, + on_stream: ffi::moq_status_callback, + user_data: *mut c_void, +) -> i32 { + ffi::enter(move || { + let endpoint = ffi::parse_id(endpoint)?; + let peer = unsafe { ffi::parse_str(peer, peer_len)? }; + let info = unsafe { info.as_ref() }.map(TryInto::try_into).transpose()?; + let callback = unsafe { OnStatus::new(user_data, on_stream)? }; + State::lock().socket.dial(endpoint, peer, Some(info), callback) + }) +} + +/// Accept `tcp` dials from peers. +/// +/// `on_incoming` fires with a positive incoming handle for each dial, then exactly once more +/// with a terminal code: `0` once the endpoint closed or after [moq_socket_cancel], or a +/// negative error, `MOQ_ERROR_UNSUPPORTED` while no peer can reach the endpoint. Accept each +/// dial with [moq_socket_incoming_accept] or refuse it with [moq_socket_incoming_reject]. Dials +/// queue until delivered, or until their dialer gives up. Run one loop per protocol. +/// +/// Returns a positive task handle, or a negative code. +/// +/// # Safety +/// - `on_incoming` must be non-NULL, and `user_data` valid until its terminal callback. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_socket_accept_tcp( + endpoint: u32, + on_incoming: ffi::moq_status_callback, + user_data: *mut c_void, +) -> i32 { + ffi::enter(move || { + let endpoint = ffi::parse_id(endpoint)?; + let callback = unsafe { OnStatus::new(user_data, on_incoming)? }; + State::lock().socket.accept(endpoint, false, callback) + }) +} + +/// Accept `track` dials from peers; see [moq_socket_accept_tcp]. +/// +/// # Safety +/// - `on_incoming` must be non-NULL, and `user_data` valid until its terminal callback. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_socket_accept_track( + endpoint: u32, + on_incoming: ffi::moq_status_callback, + user_data: *mut c_void, +) -> i32 { + ffi::enter(move || { + let endpoint = ffi::parse_id(endpoint)?; + let callback = unsafe { OnStatus::new(user_data, on_incoming)? }; + State::lock().socket.accept(endpoint, true, callback) + }) +} + +/// Stop a dial, an accept loop, or an incoming accept. +/// +/// Its callback still fires once more with a terminal `0`; release `user_data` there. A +/// stopped dial or accept resets its session. Returns zero, or a negative code if it already +/// ended. +#[unsafe(no_mangle)] +pub extern "C" fn moq_socket_cancel(task: u32) -> i32 { + ffi::enter(move || { + let task = ffi::parse_id(task)?; + State::lock().socket.tasks.close(task, Error::NotFound) + }) +} + +/// Read an incoming dial's claimed peer id and session id. +/// +/// Either output may be NULL. The strings borrow the handle until it is accepted or rejected. +/// +/// # Safety +/// - `peer` and `session` must each be NULL or point at a writable [moq_string]. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_socket_incoming_info(incoming: u32, peer: *mut moq_string, session: *mut moq_string) -> i32 { + ffi::enter(move || { + let incoming = ffi::parse_id(incoming)?; + let (peer, session) = unsafe { (peer.as_mut(), session.as_mut()) }; + State::lock().socket.incoming_info(incoming, peer, session) + }) +} + +/// Accept an incoming dial, releasing its handle. +/// +/// Verifies the dialer really dialed this session first. `info` describes this side's half of a +/// `track` session, or NULL to keep every message until read; a `tcp` session takes NULL. +/// `on_stream` fires like [moq_socket_dial_tcp]'s, and [moq_socket_cancel] gives up and resets +/// the session. +/// +/// Returns a positive task handle, or a negative code. +/// +/// # Safety +/// - `info` must be NULL or point at a [moq_track_info]. +/// - `on_stream` must be non-NULL, and `user_data` valid until its terminal callback. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_socket_incoming_accept( + incoming: u32, + info: *const moq_track_info, + on_stream: ffi::moq_status_callback, + user_data: *mut c_void, +) -> i32 { + ffi::enter(move || { + let incoming = ffi::parse_id(incoming)?; + let info = unsafe { info.as_ref() }.map(TryInto::try_into).transpose()?; + let callback = unsafe { OnStatus::new(user_data, on_stream)? }; + State::lock().socket.incoming_accept(incoming, info, callback) + }) +} + +/// Refuse an incoming dial as not found, releasing its handle. +#[unsafe(no_mangle)] +pub extern "C" fn moq_socket_incoming_reject(incoming: u32) -> i32 { + ffi::enter(move || { + let incoming = ffi::parse_id(incoming)?; + let entry = State::lock().socket.incoming.remove(incoming).ok_or(Error::NotFound)?; + match entry.inner { + IncomingKind::Tcp(incoming) => incoming.reject(), + IncomingKind::Track(incoming) => incoming.reject(), + } + Ok(()) + }) +} + +/// Read a stream's peer endpoint id and session id. +/// +/// Either output may be NULL. The strings borrow the stream handle until [moq_socket_stream_free]. +/// +/// # Safety +/// - `peer` and `session` must each be NULL or point at a writable [moq_string]. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_socket_stream_info(stream: u32, peer: *mut moq_string, session: *mut moq_string) -> i32 { + ffi::enter(move || { + let stream = ffi::parse_id(stream)?; + let (peer, session) = unsafe { (peer.as_mut(), session.as_mut()) }; + State::lock().socket.stream_info(stream, peer, session) + }) +} + +/// Take this side's half of a stream, which outlives the stream handle. +/// +/// A `tcp` session's half is a group handle: write with [crate::moq_publish_group_frame], pacing +/// with [crate::moq_publish_group_ready], and end it with [crate::moq_publish_group_finish] (or +/// abort it). Dropping it unfinished resets the session. A `track` session's half is a raw track +/// handle, written and ended with the `moq_publish_track_*` calls. +/// +/// Returns the positive handle, or a negative code once taken. +#[unsafe(no_mangle)] +pub extern "C" fn moq_socket_stream_writer(stream: u32) -> i32 { + ffi::enter(move || { + let stream = ffi::parse_id(stream)?; + let mut state = State::lock(); + let entry = state.socket.streams.get_mut(stream).ok_or(Error::NotFound)?; + let children = entry.children.clone(); + match entry.writer.take().ok_or(Error::Moq(moq_net::Error::Closed))? { + Writer::Group(group) => state.publish.socket_group(group), + Writer::Track(track) => state.publish.socket_track(track, &children), + } + }) +} + +/// Read the peer's half of a stream, which outlives the stream handle; callable once. +/// +/// Works like [crate::moq_consume_track]: `on_frame` fires with a positive frame handle for each +/// frame in order, read with [crate::moq_consume_track_frame] and released with +/// [crate::moq_consume_track_frame_free], then exactly once more with a terminal code: `0` once +/// the peer finished (or after [crate::moq_consume_track_cancel]), or a negative error when it +/// reset. A `track` session's half is subscribed reliably and oldest first; +/// [crate::moq_consume_track_update] changes that, while a `tcp` session's refuses it with +/// `MOQ_ERROR_UNSUPPORTED`. +/// +/// Returns a positive track handle, or a negative code once taken. +/// +/// # Safety +/// - `on_frame` must be non-NULL, and `user_data` valid until its terminal callback. +#[unsafe(no_mangle)] +pub unsafe extern "C" fn moq_socket_stream_reader( + stream: u32, + on_frame: ffi::moq_status_callback, + user_data: *mut c_void, +) -> i32 { + ffi::enter(move || { + let stream = ffi::parse_id(stream)?; + let callback = unsafe { OnStatus::new(user_data, on_frame)? }; + let mut state = State::lock(); + let entry = state.socket.streams.get_mut(stream).ok_or(Error::NotFound)?; + let driver = entry.driver.clone(); + let half = entry.reader.take().ok_or(Error::Moq(moq_net::Error::Closed))?; + state.consume.socket_read(half, driver, callback) + }) +} + +/// Release a stream handle. +/// +/// A half not yet taken is dropped: an unfinished `tcp` writer resets the session, and an +/// unread reader stops reading. Taken halves are unaffected. +#[unsafe(no_mangle)] +pub extern "C" fn moq_socket_stream_free(stream: u32) -> i32 { + ffi::enter(move || { + let stream = ffi::parse_id(stream)?; + let entry = State::lock().socket.streams.remove(stream).ok_or(Error::NotFound)?; + drop(entry); + Ok(()) + }) +} diff --git a/rs/moq-c/src/state.rs b/rs/moq-c/src/state.rs index da81ad6d76b..f15f5b2f03c 100644 --- a/rs/moq-c/src/state.rs +++ b/rs/moq-c/src/state.rs @@ -2,6 +2,7 @@ use std::sync::{Arc, LazyLock, Mutex, MutexGuard, PoisonError}; use crate::auth::Auth; use crate::encoder::Encoders; +use crate::socket::Socket; use crate::bandwidth::Bandwidth; use crate::{Consume, Origin, Publish, Server, Session, audio::Audio, video::Video}; @@ -16,6 +17,7 @@ pub struct State { pub bandwidth: Bandwidth, pub auth: Auth, pub encoders: Encoders, + pub socket: Socket, } impl State { @@ -31,6 +33,7 @@ impl State { bandwidth: Bandwidth::default(), auth: Auth::default(), encoders: Encoders::default(), + socket: Socket::default(), } } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 41bbe585938..3bc58854e59 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -5,6 +5,8 @@ use std::ffi::{c_char, c_void}; use std::sync::mpsc; use std::time::Duration; +mod parity; + const TIMEOUT: Duration = Duration::from_secs(10); /// A timestamp of `value` microseconds. @@ -1149,8 +1151,8 @@ fn publish_catalog_roundtrip() { coded_width: width, coded_height: height, container: moq_container::default(), - warmup_us: 0, - has_warmup: false, + warmup_us: 250_000, + has_warmup: true, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); let disabled_video_name = "video-disabled"; @@ -1209,10 +1211,10 @@ fn publish_catalog_roundtrip() { sample_rate: 48000, channel_count: 2, container: moq_container::default(), - jitter_us: 0, - has_jitter: false, - warmup_us: 0, - has_warmup: false, + jitter_us: 20_000, + has_jitter: true, + warmup_us: 40_000, + has_warmup: true, }; assert_eq!(unsafe { moq_publish_audio_config(broadcast, &audio) }, 0); @@ -1254,6 +1256,7 @@ fn publish_catalog_roundtrip() { ); assert_eq!(video_cfg.coded_width, 1920); assert_eq!(video_cfg.coded_height, 1080); + assert_eq!((video_cfg.warmup_us, video_cfg.has_warmup), (250_000, true)); let mut enabled = std::mem::MaybeUninit::::uninit(); assert_eq!( unsafe { moq_consume_video_enabled(catalog_id, 0, enabled.as_mut_ptr()) }, @@ -1319,6 +1322,8 @@ fn publish_catalog_roundtrip() { ); assert_eq!(audio_cfg.sample_rate, 48000); assert_eq!(audio_cfg.channel_count, 2); + assert_eq!((audio_cfg.jitter_us, audio_cfg.has_jitter), (20_000, true)); + assert_eq!((audio_cfg.warmup_us, audio_cfg.has_warmup), (40_000, true)); // Removing the video rendition republishes a catalog without it. assert_eq!( diff --git a/rs/moq-c/src/test/parity.rs b/rs/moq-c/src/test/parity.rs new file mode 100644 index 00000000000..12421f8b220 --- /dev/null +++ b/rs/moq-c/src/test/parity.rs @@ -0,0 +1,495 @@ +//! The binding features moq-c gained to match moq-ffi for the cut. + +use super::*; + +/// Open the socket endpoint `name` under `room` on `origin`. +fn endpoint(origin: u32, name: &str) -> u32 { + let room = "room"; + id(unsafe { + moq_socket_create( + origin, + room.as_ptr().cast(), + room.len(), + name.as_ptr().cast(), + name.len(), + ) + }) +} + +/// Read a `moq_string` a handle lends. +fn lent(s: moq_string) -> String { + borrowed_string(s.data, s.len).unwrap_or_default() +} + +/// Read the next raw frame delivered to `cb`, releasing it. +fn next_frame(cb: &Callback) -> Vec { + let frame_id = id(cb.recv()); + let mut frame: moq_frame = unsafe { std::mem::zeroed() }; + assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); + let payload = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }.to_vec(); + assert_eq!(moq_consume_track_frame_free(frame_id), 0); + payload +} + +/// Dial `b` from `a` and accept it, returning (dialed, accepted) stream handles plus the +/// callbacks that must outlive them. +fn connect(a: u32, b: u32, track: bool) -> (u32, u32, [Callback; 3]) { + let accepts = Callback::new(); + let _accept = id(unsafe { + match track { + false => moq_socket_accept_tcp(b, Some(channel_callback), accepts.ptr), + true => moq_socket_accept_track(b, Some(channel_callback), accepts.ptr), + } + }); + let dialed = Callback::new(); + let peer = "b"; + let _dial = id(unsafe { + match track { + false => moq_socket_dial_tcp(a, peer.as_ptr().cast(), peer.len(), Some(channel_callback), dialed.ptr), + true => moq_socket_dial_track( + a, + peer.as_ptr().cast(), + peer.len(), + std::ptr::null(), + Some(channel_callback), + dialed.ptr, + ), + } + }); + + let incoming = id(accepts.recv()); + let (mut claimed, mut session) = (moq_str(""), moq_str("")); + assert_eq!(unsafe { moq_socket_incoming_info(incoming, &mut claimed, &mut session) }, 0); + assert_eq!(lent(claimed), "a"); + let accepted = Callback::new(); + let _accepting = + id(unsafe { moq_socket_incoming_accept(incoming, std::ptr::null(), Some(channel_callback), accepted.ptr) }); + assert!( + unsafe { moq_socket_incoming_info(incoming, &mut claimed, &mut session) } < 0, + "accepting releases the incoming handle" + ); + + let client = id(dialed.recv()); + assert_eq!(dialed.recv_terminal(), 0); + let server = id(accepted.recv()); + assert_eq!(accepted.recv_terminal(), 0); + (client, server, [accepts, dialed, accepted]) +} + +#[test] +fn socket_tcp_round_trip() { + let origin = id(moq_origin_create()); + let (a, b) = (endpoint(origin, "a"), endpoint(origin, "b")); + let (client, server, [accepts, ..]) = connect(a, b, false); + + let (mut peer, mut session) = (moq_str(""), moq_str("")); + assert_eq!(unsafe { moq_socket_stream_info(client, &mut peer, &mut session) }, 0); + assert_eq!(lent(peer), "b"); + let client_session = lent(session); + assert_eq!(unsafe { moq_socket_stream_info(server, &mut peer, std::ptr::null_mut()) }, 0); + assert_eq!(lent(peer), "a"); + assert_eq!(unsafe { moq_socket_stream_info(server, std::ptr::null_mut(), &mut session) }, 0); + assert_eq!(lent(session), client_session, "both sides share the dialer's session id"); + + let writer = id(moq_socket_stream_writer(client)); + assert!(moq_socket_stream_writer(client) < 0, "the writer is taken once"); + let frames = Callback::new(); + let reader = id(unsafe { moq_socket_stream_reader(server, Some(channel_callback), frames.ptr) }); + assert!( + unsafe { moq_socket_stream_reader(server, Some(ignore_callback), std::ptr::null_mut()) } < 0, + "the reader is taken once" + ); + assert_eq!( + unsafe { moq_consume_track_update(reader, std::ptr::null()) }, + MOQ_ERROR_UNSUPPORTED, + "a tcp half has no subscription" + ); + // The halves outlive the stream handles. Take the reverse writer first: dropping it + // unfinished would reset the session. + let reverse = id(moq_socket_stream_writer(server)); + assert_eq!(moq_socket_stream_free(server), 0); + + for part in [b"one".as_slice(), b"two"] { + assert_eq!( + unsafe { moq_publish_group_frame(writer, part.as_ptr(), part.len(), std::ptr::null()) }, + 0 + ); + } + assert_eq!(moq_publish_group_finish(writer), 0); + assert_eq!(next_frame(&frames), b"one"); + assert_eq!(next_frame(&frames), b"two"); + assert_eq!(frames.recv_terminal(), 0, "a finished writer ends the reader cleanly"); + assert_eq!(moq_publish_group_finish(reverse), 0); + + assert_eq!(moq_socket_stream_free(client), 0); + assert_eq!(moq_socket_close(b), 0); + assert_eq!(accepts.recv_terminal(), 0, "closing the endpoint ends its accept loop"); + assert!(moq_socket_close(b) < 0); + assert_eq!(moq_socket_close(a), 0); + assert_eq!(moq_origin_close(origin), 0); +} + +#[test] +fn socket_track_round_trip_and_endpoint_close() { + let origin = id(moq_origin_create()); + let (a, b) = (endpoint(origin, "a"), endpoint(origin, "b")); + let (client, server, [accepts, ..]) = connect(a, b, true); + + let track = id(moq_socket_stream_writer(client)); + let frames = Callback::new(); + let _reader = id(unsafe { moq_socket_stream_reader(server, Some(channel_callback), frames.ptr) }); + for part in [b"first".as_slice(), b"later"] { + let group = id(moq_publish_track_group(track)); + assert_eq!( + unsafe { moq_publish_group_frame(group, part.as_ptr(), part.len(), std::ptr::null()) }, + 0 + ); + assert_eq!(moq_publish_group_finish(group), 0); + } + assert_eq!(next_frame(&frames), b"first"); + assert_eq!(next_frame(&frames), b"later"); + + // Closing the endpoint ends its open track halves. + assert_eq!(moq_socket_close(a), 0); + assert!(moq_publish_track_finish(track) < 0, "the endpoint's close released the track"); + assert!(frames.recv_terminal() < 0, "the peer's half reset"); + + assert_eq!(moq_socket_stream_free(client), 0); + assert_eq!(moq_socket_stream_free(server), 0); + assert_eq!(moq_socket_close(b), 0); + assert_eq!(accepts.recv_terminal(), 0); + assert_eq!(moq_origin_close(origin), 0); +} + +#[test] +fn socket_reject_and_cancel() { + let origin = id(moq_origin_create()); + let (a, b) = (endpoint(origin, "a"), endpoint(origin, "b")); + let accepts = Callback::new(); + let accept = id(unsafe { moq_socket_accept_tcp(b, Some(channel_callback), accepts.ptr) }); + + let dialed = Callback::new(); + let peer = "b"; + let _dial = + id(unsafe { moq_socket_dial_tcp(a, peer.as_ptr().cast(), peer.len(), Some(channel_callback), dialed.ptr) }); + let incoming = id(accepts.recv()); + assert_eq!(moq_socket_incoming_reject(incoming), 0); + assert!(moq_socket_incoming_reject(incoming) < 0, "rejecting releases the handle"); + assert!(dialed.recv_terminal() < 0, "a rejected dial fails"); + + // Dialing oneself is refused at once. + let me = "a"; + assert_eq!( + unsafe { moq_socket_dial_tcp(a, me.as_ptr().cast(), me.len(), Some(ignore_callback), std::ptr::null_mut()) }, + MOQ_ERROR_UNSUPPORTED + ); + + // A pending dial gives up when cancelled. + let waiting = Callback::new(); + let absent = "nobody"; + let dial = id(unsafe { + moq_socket_dial_tcp(a, absent.as_ptr().cast(), absent.len(), Some(channel_callback), waiting.ptr) + }); + assert_eq!(moq_socket_cancel(dial), 0); + assert_eq!(waiting.recv_terminal(), 0); + + assert_eq!(moq_socket_cancel(accept), 0); + assert_eq!(accepts.recv_terminal(), 0); + assert!(moq_socket_cancel(accept) < 0); + assert_eq!(moq_socket_close(a), 0); + assert_eq!(moq_socket_close(b), 0); + assert_eq!(moq_origin_close(origin), 0); +} + +#[test] +fn consume_closed_fires_when_the_broadcast_ends() { + let origin = id(moq_origin_create()); + let path = b"closed-watch"; + let broadcast = publish_broadcast(origin, path); + let consume = request_broadcast(origin, path); + + let cancelled = Callback::new(); + let watcher = id(unsafe { moq_consume_closed(consume, Some(channel_callback), cancelled.ptr) }); + assert_eq!(moq_consume_closed_cancel(watcher), 0); + assert_eq!(cancelled.recv_terminal(), 0); + assert!(moq_consume_closed_cancel(watcher) < 0); + + let closed = Callback::new(); + let _watcher = id(unsafe { moq_consume_closed(consume, Some(channel_callback), closed.ptr) }); + assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(closed.recv_terminal(), 0); + + assert_eq!(moq_consume_close(consume), 0); + assert_eq!(moq_origin_close(origin), 0); +} + +#[test] +fn track_largest_and_group_ready() { + let origin = id(moq_origin_create()); + let broadcast = publish_broadcast(origin, b"largest"); + let track = publish_named_track(broadcast, b"data"); + + let (mut group, mut frame, mut present) = (9, 9, true); + assert_eq!( + unsafe { moq_publish_track_largest(track, &mut group, &mut frame, &mut present) }, + 0 + ); + assert!(!present, "an empty track has no largest position"); + + let first = id(moq_publish_track_group_at(track, 3)); + for part in [b"a".as_slice(), b"b"] { + assert_eq!( + unsafe { moq_publish_group_frame(first, part.as_ptr(), part.len(), µs(0)) }, + 0 + ); + } + assert_eq!( + unsafe { moq_publish_track_largest(track, &mut group, &mut frame, &mut present) }, + 0 + ); + assert!(present); + assert_eq!((group, frame), (3, 1)); + + // Nobody reads the group, so the wait resolves once the group is finished. + let ready = Callback::new(); + assert_eq!( + unsafe { moq_publish_group_ready(first, 1, Some(channel_callback), ready.ptr) }, + 0 + ); + // Let the wait park first: finishing must still end it, though moq-net does not wake + // `poll_ready` on a finish. + std::thread::sleep(Duration::from_millis(50)); + assert_eq!(moq_publish_group_finish(first), 0); + assert_eq!(ready.rx.recv_timeout(Duration::from_secs(2)), Ok(0)); + assert!( + unsafe { moq_publish_group_ready(first, 1, Some(ignore_callback), std::ptr::null_mut()) } < 0, + "a finished group's handle is gone" + ); + + assert_eq!(moq_publish_track_finish(track), 0); + assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(moq_origin_close(origin), 0); +} + +#[test] +fn timebase_handles_are_owned_by_their_broadcast() { + let origin = id(moq_origin_create()); + let broadcast = publish_broadcast(origin, b"timebase"); + let timebase = id(moq_publish_timebase(broadcast)); + assert_eq!(moq_publish_timebase_free(timebase), 0); + assert!(moq_publish_timebase_free(timebase) < 0); + assert!(moq_publish_timebase(0) < 0); + + let kept = id(moq_publish_timebase(broadcast)); + assert_eq!(moq_publish_close(broadcast), 0); + // The handle outlives the broadcast, which already let go of the timebase itself. + assert_eq!(moq_publish_timebase_free(kept), 0); + assert_eq!(moq_origin_close(origin), 0); +} + +#[test] +fn client_once_and_server_quic_options_parse() { + let mut config = client_config(); + assert!(!parsed(&config).once); + config.once = true; + assert!(parsed(&config).once); + + let bind = "127.0.0.1:0"; + let generate = [moq_str("localhost")]; + let versions = [moq_str("moq-lite-03")]; + let mut server: moq_server_config = unsafe { std::mem::zeroed() }; + server.bind = bind.as_ptr().cast(); + server.bind_len = bind.len(); + server.tls_generate = generate.as_ptr(); + server.tls_generate_len = generate.len(); + server.versions = versions.as_ptr(); + server.versions_len = versions.len(); + server.quic_max_streams = 64; + server.has_quic_max_streams = true; + server.quic_idle_timeout_us = 5_000_000; + server.has_quic_idle_timeout = true; + let cb = Callback::new(); + let listening = id(unsafe { moq_server_listen(&server, Some(channel_callback), cb.ptr) }); + assert_eq!(moq_server_close(listening), 0); + assert_eq!(cb.recv_terminal(), 0); + + let bogus = [moq_str("moq-nope")]; + server.versions = bogus.as_ptr(); + assert_eq!( + unsafe { moq_server_listen(&server, Some(ignore_callback), std::ptr::null_mut()) }, + MOQ_ERROR_INVALID_CONFIG, + "an unknown version is refused" + ); +} + +#[test] +fn session_tokens_and_grants() { + let served = id(moq_origin_create()); + let server_cb = Callback::new(); + let (server, addr, fingerprint) = listen(&server_cb); + let received = id(moq_origin_create()); + let client_cb = States::new(); + let client = dial_pinned(&format!("https://{addr}/"), &fingerprint, 0, received, client_cb.ptr); + + let request = id(server_cb.recv()); + let session_cb = States::new(); + let session = id(unsafe { moq_session_request_accept(request, served, 0, Some(state_callback), session_cb.ptr) }); + for cb in [&session_cb, &client_cb] { + assert_eq!(cb.recv().phase, moq_connection_phase::MOQ_CONNECTION_PHASE_CONNECTED); + } + + // An accepted session presents no tokens. + let token = [moq_str("token")]; + assert_eq!( + unsafe { moq_session_tokens_set(session, token.as_ptr(), token.len()) }, + MOQ_ERROR_UNSUPPORTED + ); + assert_eq!( + unsafe { moq_session_tokens_answered(session, Some(ignore_callback), std::ptr::null_mut()) }, + MOQ_ERROR_UNSUPPORTED + ); + // A dialed session refuses an empty token, and takes real ones. + let empty = [moq_str("")]; + assert_eq!( + unsafe { moq_session_tokens_set(client, empty.as_ptr(), empty.len()) }, + MOQ_ERROR_INVALID_CONFIG + ); + assert_eq!(unsafe { moq_session_tokens_set(client, token.as_ptr(), token.len()) }, 0); + + // The grant is delivered at once; the default protocol carries no AUTH, so it stays absent. + let grants = Callback::new(); + let watcher = id(unsafe { moq_session_grants(client, Some(channel_callback), grants.ptr) }); + let grant = id(grants.recv()); + let mut info: moq_grant = unsafe { std::mem::zeroed() }; + info.present = true; + assert_eq!(unsafe { moq_grant_info(grant, &mut info) }, 0); + assert!(!info.present); + assert_eq!((info.publish_len, info.subscribe_len), (0, 0)); + assert_eq!(moq_grant_free(grant), 0); + assert!(moq_grant_free(grant) < 0); + assert_eq!(moq_session_grants_cancel(watcher), 0); + loop { + let code = grants.recv(); + if code <= 0 { + assert_eq!(code, 0); + break; + } + assert_eq!(moq_grant_free(id(code)), 0); + } + + assert_eq!(moq_session_close(session), 0); + session_cb.recv_terminal(); + assert_eq!(moq_session_close(client), 0); + client_cb.recv_terminal(); + assert_eq!(moq_server_close(server), 0); + assert_eq!(server_cb.recv_terminal(), 0); + assert_eq!(moq_origin_close(served), 0); + assert_eq!(moq_origin_close(received), 0); +} + +#[test] +fn audio_encoder_without_a_broadcast() { + let codec = b"opus"; + let output = moq_audio_encoder_output { + codec: codec.as_ptr().cast(), + codec_len: codec.len(), + sample_rate: 0, + channels: 0, + bitrate: 0, + frame_duration_us: 20_000, + }; + let encoder = id(unsafe { moq_audio_encoder_create(&output) }); + let frame_size = moq_audio_encoder_frame_size(encoder); + assert_eq!(frame_size, 960, "20 ms at the default 48 kHz"); + let mut init: moq_audio_init = unsafe { std::mem::zeroed() }; + assert_eq!(unsafe { moq_audio_encoder_init(encoder, &mut init) }, 0); + assert_eq!(moq_audio_encoder_bitrate(encoder, 64_000), 0); + + // Stereo by default, so a frame is twice the frame size in interleaved samples. + let pcm = vec![0.0f32; frame_size as usize * 2]; + let mut packets = 0; + for _ in 0..3 { + let count = unsafe { moq_audio_encoder_encode(encoder, pcm.as_ptr(), pcm.len()) }; + assert!(count >= 0, "encode failed: {count}"); + packets += count; + } + let mut padding = 0; + let drained = unsafe { moq_audio_encoder_finish(encoder, pcm.as_ptr(), pcm.len() / 2, &mut padding) }; + assert!(drained >= 0, "finish failed: {drained}"); + assert!(packets + drained > 0, "the encoder produced packets"); + if drained > 0 { + let mut packet: moq_frame = unsafe { std::mem::zeroed() }; + assert_eq!(unsafe { moq_audio_encoder_packet(encoder, 0, &mut packet) }, 0); + assert!(packet.payload_size > 0); + assert!(unsafe { moq_audio_encoder_packet(encoder, drained as u32, &mut packet) } < 0); + } + assert!( + unsafe { moq_audio_encoder_encode(encoder, pcm.as_ptr(), pcm.len()) } < 0, + "a finished encoder takes no more" + ); + assert_eq!(moq_audio_encoder_free(encoder), 0); + assert!(moq_audio_encoder_free(encoder) < 0); +} + +#[test] +fn video_encoder_without_a_broadcast() { + let input = moq_video_encoder_input { + format: moq_video_pixel_format::MOQ_VIDEO_PIXEL_FORMAT_RGBA as u32, + width: 320, + height: 240, + framerate: moq_video_frame_rate { + numerator: 30, + denominator: 1, + }, + }; + let output = moq_video_encoder_output { + codec: moq_video_codec::MOQ_VIDEO_CODEC_H264 as u32, + bitrate: 0, + gop: 0, + kind: moq_video_encoder_kind::MOQ_VIDEO_ENCODER_KIND_SOFTWARE as u32, + encoder: std::ptr::null(), + encoder_len: 0, + }; + let encoder = id(unsafe { moq_video_encoder_create(&input, &output) }); + let rgba = gray_rgba(320, 240); + let mut packets = 0; + for index in 0..5 { + let frame = moq_video_encoder_frame { + timestamp: micros(index * 33_333), + data: rgba.as_ptr(), + data_size: rgba.len(), + }; + let count = unsafe { moq_video_encoder_encode(encoder, &frame) }; + assert!(count >= 0, "encode failed: {count}"); + packets += count; + } + assert_eq!(moq_video_encoder_cut(encoder), 0); + let drained = moq_video_encoder_finish(encoder); + assert!(drained >= 0, "finish failed: {drained}"); + assert!(packets + drained > 0, "the encoder produced access units"); + if drained > 0 { + let mut packet: moq_frame = unsafe { std::mem::zeroed() }; + assert_eq!(unsafe { moq_video_encoder_packet(encoder, 0, &mut packet) }, 0); + assert!(packet.payload_size > 0); + } + assert!(moq_video_encoder_finish(encoder) < 0, "finishing twice fails"); + assert_eq!(moq_video_encoder_free(encoder), 0); +} + +/// Only Apple decoders hand out a native surface; elsewhere asking for one is refused up front. +#[cfg(not(any(target_os = "macos", target_os = "ios")))] +#[test] +fn native_surfaces_are_unsupported_off_apple() { + let output = moq_video_decoder_output { + delay: moq_delay::default(), + format: moq_video_pixel_format::MOQ_VIDEO_PIXEL_FORMAT_I420 as u32, + width: 0, + height: 0, + start: 0, + surface: true, + }; + assert_eq!( + unsafe { moq_decode_video(1, 0, &output, Some(ignore_callback), std::ptr::null_mut()) }, + MOQ_ERROR_UNSUPPORTED + ); +} From c851f4bafc35b1efd78f6ffc83dcf7b95e345dd6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 12:36:13 -0800 Subject: [PATCH 06/16] wip(moq-c): rendition references on video and audio configs Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/api.rs | 65 +++++++++++++++ rs/moq-c/src/consume.rs | 66 +++++++++++++++ rs/moq-c/src/test.rs | 176 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 307 insertions(+) diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 08d64840783..95330886e3b 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -444,6 +444,19 @@ pub struct moq_video_config { pub warmup_us: u64, /// Whether `warmup_us` is present; absent means none. pub has_warmup: bool, + /// The broadcast holding the rendition's track, relative to the catalog's own broadcast + /// (`./source`), or NULL when it is the catalog's broadcast. + pub broadcast: *const c_char, + /// Length of `broadcast` in bytes. + pub broadcast_len: usize, + /// The stream instance `broadcast` must resolve to, or NULL for whichever resolves first. + pub instance: *const c_char, + /// Length of `instance` in bytes. + pub instance_len: usize, + /// The track's name in its broadcast, or NULL when it is `name`. + pub track: *const c_char, + /// Length of `track` in bytes. + pub track_len: usize, } /// Catalog properties shared by every video rendition. @@ -515,6 +528,19 @@ pub struct moq_audio_config { pub warmup_us: u64, /// Whether `warmup_us` is present; absent means none. pub has_warmup: bool, + /// The broadcast holding the rendition's track, relative to the catalog's own broadcast + /// (`./source`), or NULL when it is the catalog's broadcast. + pub broadcast: *const c_char, + /// Length of `broadcast` in bytes. + pub broadcast_len: usize, + /// The stream instance `broadcast` must resolve to, or NULL for whichever resolves first. + pub instance: *const c_char, + /// Length of `instance` in bytes. + pub instance_len: usize, + /// The track's name in its broadcast, or NULL when it is `name`. + pub track: *const c_char, + /// Length of `track` in bytes. + pub track_len: usize, } /// Options for a JSON snapshot producer (lossy latest-value mode). @@ -3109,11 +3135,43 @@ pub unsafe extern "C" fn moq_publish_video_config(broadcast: u32, config: *const video.coded_height = (config.coded_height > 0).then_some(config.coded_height); video.container = unsafe { parse_container(&config.container)? }; video.warmup = config.has_warmup.then(|| std::time::Duration::from_micros(config.warmup_us)); + (video.broadcast, video.instance, video.track) = unsafe { + parse_reference( + (config.broadcast, config.broadcast_len), + (config.instance, config.instance_len), + (config.track, config.track_len), + )? + }; State::lock().publish.video_config(broadcast, name, video) }) } +/// A rendition's reference fields, as [moq_video_config] and [moq_audio_config] carry them. +/// +/// # Safety +/// - Each non-NULL pointer must be valid for its length. +unsafe fn parse_reference( + broadcast: (*const c_char, usize), + instance: (*const c_char, usize), + track: (*const c_char, usize), +) -> Result<(Option, Option, Option), Error> { + let broadcast = unsafe { ffi::parse_str_optional(broadcast.0, broadcast.1)? } + .filter(|broadcast| !broadcast.is_empty()) + .map(moq_net::path::Relative::new) + .transpose() + .map_err(|err| Error::InvalidConfig(err.to_string()))?; + let instance = unsafe { ffi::parse_str_optional(instance.0, instance.1)? } + .filter(|instance| !instance.is_empty()) + .map(moq_net::Instance::from_str) + .transpose() + .map_err(|err| Error::InvalidConfig(err.to_string()))?; + let track = unsafe { ffi::parse_str_optional(track.0, track.1)? } + .filter(|track| !track.is_empty()) + .map(str::to_string); + Ok((broadcast, instance, track)) +} + /// Add or replace an audio rendition in a broadcast's catalog. /// /// This is the producer counterpart to [moq_consume_audio_config]. The rendition @@ -3157,6 +3215,13 @@ pub unsafe extern "C" fn moq_publish_audio_config(broadcast: u32, config: *const } audio.jitter = config.has_jitter.then(|| std::time::Duration::from_micros(config.jitter_us)); audio.warmup = config.has_warmup.then(|| std::time::Duration::from_micros(config.warmup_us)); + (audio.broadcast, audio.instance, audio.track) = unsafe { + parse_reference( + (config.broadcast, config.broadcast_len), + (config.instance, config.instance_len), + (config.track, config.track_len), + )? + }; State::lock().publish.audio_config(broadcast, name, audio) }) diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index 2ed5857526d..7dc13e82902 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -37,11 +37,36 @@ struct ConsumeCatalog { audio_codec: Vec, video_codec: Vec, + /// Each rendition's broadcast reference and instance as strings, for the same reason. + audio_ref: Vec, + video_ref: Vec, + /// Section names and their JSON, serialized on the heap so the section iterator /// and direct-lookup APIs can hand C borrowed pointers into stable storage. sections: Vec<(String, String)>, } +/// A rendition's reference, rendered once so C can borrow it. +#[derive(Default)] +struct Reference { + broadcast: Option, + instance: Option, +} + +impl Reference { + fn new(broadcast: &Option, instance: &Option) -> Self { + Self { + broadcast: broadcast.as_ref().map(ToString::to_string), + instance: instance.as_ref().map(ToString::to_string), + } + } +} + +/// Borrow an optional string as a C pointer and length, NULL when absent. +fn lend(value: Option<&String>) -> (*const c_char, usize) { + value.map_or((std::ptr::null(), 0), |value| (value.as_ptr().cast(), value.len())) +} + impl ConsumeCatalog { fn rendition(&self, name: &str, config: &C) -> Rendition { Rendition { @@ -378,6 +403,19 @@ impl Consume { .map(|config| config.codec.to_string()) .collect(); + let audio_ref = update + .audio + .renditions + .values() + .map(|config| Reference::new(&config.broadcast, &config.instance)) + .collect(); + let video_ref = update + .video + .renditions + .values() + .map(|config| Reference::new(&config.broadcast, &config.instance)) + .collect(); + // Serialize the untyped application sections to owned strings so the // C section APIs can borrow stable pointers from the snapshot. let sections = update @@ -392,6 +430,8 @@ impl Consume { catalog: update, audio_codec, video_codec, + audio_ref, + video_ref, sections, }; @@ -412,6 +452,10 @@ impl Consume { .nth(index) .ok_or(Error::NoIndex)?; let codec = consume.video_codec.get(index).ok_or(Error::NoIndex)?; + let reference = consume.video_ref.get(index).ok_or(Error::NoIndex)?; + let (broadcast, broadcast_len) = lend(reference.broadcast.as_ref()); + let (instance, instance_len) = lend(reference.instance.as_ref()); + let (track, track_len) = lend(config.track.as_ref()); *dst = moq_video_config { preference: config.preference, @@ -436,6 +480,12 @@ impl Consume { label_len: config.label.as_ref().map_or(0, String::len), warmup_us: micros(config.warmup), has_warmup: config.warmup.is_some(), + broadcast, + broadcast_len, + instance, + instance_len, + track, + track_len, }; Ok(()) @@ -482,6 +532,10 @@ impl Consume { .nth(index) .ok_or(Error::NoIndex)?; let codec = consume.audio_codec.get(index).ok_or(Error::NoIndex)?; + let reference = consume.audio_ref.get(index).ok_or(Error::NoIndex)?; + let (broadcast, broadcast_len) = lend(reference.broadcast.as_ref()); + let (instance, instance_len) = lend(reference.instance.as_ref()); + let (track, track_len) = lend(config.track.as_ref()); *dst = moq_audio_config { name: rendition.as_str().as_ptr() as *const c_char, @@ -507,6 +561,12 @@ impl Consume { has_jitter: config.jitter.is_some(), warmup_us: micros(config.warmup), has_warmup: config.warmup.is_some(), + broadcast, + broadcast_len, + instance, + instance_len, + track, + track_len, }; Ok(()) @@ -1330,6 +1390,8 @@ mod supervision_tests { catalog, audio_codec: Vec::new(), video_codec: Vec::new(), + audio_ref: Vec::new(), + video_ref: Vec::new(), sections: Vec::new(), }) .unwrap(); @@ -1364,6 +1426,8 @@ mod rendition_tests { catalog, audio_codec: Vec::new(), video_codec: Vec::new(), + audio_ref: Vec::new(), + video_ref: Vec::new(), sections: Vec::new(), }) .unwrap(); @@ -1512,6 +1576,8 @@ mod tests { catalog, audio_codec: Vec::new(), video_codec: Vec::new(), + audio_ref: Vec::new(), + video_ref: Vec::new(), sections: Vec::new(), }) .unwrap(); diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 3bc58854e59..d2c7b9f4a86 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -700,6 +700,12 @@ fn publish_media_labels_config_without_naming_track() { has_jitter: false, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id1, 0, &mut audio_cfg) }, 0); assert_eq!( @@ -773,6 +779,12 @@ fn publish_catalog_config_invalid_broadcast() { container: moq_container::default(), warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert!(unsafe { moq_publish_video_config(0, &video) } < 0); assert!(unsafe { moq_publish_video_properties(0, &moq_video_properties::default()) } < 0); @@ -794,6 +806,12 @@ fn publish_catalog_config_invalid_broadcast() { has_jitter: false, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert!(unsafe { moq_publish_audio_config(0, &audio) } < 0); @@ -835,6 +853,12 @@ fn publish_media_owns_its_rendition_before_the_first_keyframe() { container: moq_container::default(), warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!( unsafe { moq_publish_video_config(broadcast, &video) }, @@ -888,6 +912,12 @@ fn publish_video_config_replaces_its_own_rendition() { container: moq_container::default(), warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); @@ -935,6 +965,12 @@ fn manual_video_identity_change_is_refused() { preference: 0, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); let next = "vp09.00.10.08"; @@ -973,6 +1009,12 @@ fn manual_audio_identity_change_is_refused() { has_jitter: false, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_publish_audio_config(broadcast, &audio) }, 0); audio.label = label.as_ptr().cast(); @@ -1138,6 +1180,9 @@ fn publish_catalog_roundtrip() { let width: u32 = 1920; let height: u32 = 1080; let description: &[u8] = &[0x01, 0x02, 0x03]; + let reference = "./source"; + let instance = fresh_instance(); + let track = "video-track"; let video = moq_video_config { preference: 0, name: video_name.as_ptr() as *const c_char, @@ -1153,6 +1198,12 @@ fn publish_catalog_roundtrip() { container: moq_container::default(), warmup_us: 250_000, has_warmup: true, + broadcast: reference.as_ptr().cast(), + broadcast_len: reference.len(), + instance: instance.as_ptr().cast(), + instance_len: instance.len(), + track: track.as_ptr().cast(), + track_len: track.len(), }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); let disabled_video_name = "video-disabled"; @@ -1171,6 +1222,12 @@ fn publish_catalog_roundtrip() { container: moq_container::default(), warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &disabled_video) }, 0); { @@ -1215,6 +1272,12 @@ fn publish_catalog_roundtrip() { has_jitter: true, warmup_us: 40_000, has_warmup: true, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_publish_audio_config(broadcast, &audio) }, 0); @@ -1240,6 +1303,12 @@ fn publish_catalog_roundtrip() { container: moq_container::default(), warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_consume_video_config(catalog_id, 0, &mut video_cfg) }, 0); let codec = unsafe { @@ -1257,6 +1326,10 @@ fn publish_catalog_roundtrip() { assert_eq!(video_cfg.coded_width, 1920); assert_eq!(video_cfg.coded_height, 1080); assert_eq!((video_cfg.warmup_us, video_cfg.has_warmup), (250_000, true)); + // Normalized: a reader sees the plain relative path. + assert_eq!(borrowed_string(video_cfg.broadcast, video_cfg.broadcast_len).as_deref(), Some("source")); + assert_eq!(borrowed_string(video_cfg.instance, video_cfg.instance_len), Some(instance.clone())); + assert_eq!(borrowed_string(video_cfg.track, video_cfg.track_len).as_deref(), Some(track)); let mut enabled = std::mem::MaybeUninit::::uninit(); assert_eq!( unsafe { moq_consume_video_enabled(catalog_id, 0, enabled.as_mut_ptr()) }, @@ -1314,6 +1387,12 @@ fn publish_catalog_roundtrip() { has_jitter: false, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id, 0, &mut audio_cfg) }, 0); assert_eq!( @@ -1324,6 +1403,7 @@ fn publish_catalog_roundtrip() { assert_eq!(audio_cfg.channel_count, 2); assert_eq!((audio_cfg.jitter_us, audio_cfg.has_jitter), (20_000, true)); assert_eq!((audio_cfg.warmup_us, audio_cfg.has_warmup), (40_000, true)); + assert!(audio_cfg.broadcast.is_null() && audio_cfg.instance.is_null() && audio_cfg.track.is_null()); // Removing the video rendition republishes a catalog without it. assert_eq!( @@ -1373,6 +1453,12 @@ fn a_half_specified_coded_size_round_trips() { container: moq_container::default(), warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); @@ -1396,6 +1482,12 @@ fn a_half_specified_coded_size_round_trips() { container: moq_container::default(), warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_consume_video_config(catalog, 0, &mut read) }, 0); assert_eq!(read.preference, -1); @@ -1464,6 +1556,12 @@ fn raw_loc_video_uses_the_declared_catalog_container() { }, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); @@ -1488,6 +1586,12 @@ fn raw_loc_video_uses_the_declared_catalog_container() { container: moq_container::default(), warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_consume_video_config(catalog, 0, &mut video_cfg) }, 0); assert_eq!( @@ -1569,6 +1673,12 @@ fn cmaf_catalog_container_carries_its_init_segment() { has_jitter: false, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_publish_audio_config(broadcast, &audio) }, 0); @@ -1593,6 +1703,12 @@ fn cmaf_catalog_container_carries_its_init_segment() { has_jitter: false, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_consume_audio_config(catalog, 0, &mut audio_cfg) }, 0); assert_eq!( @@ -1634,6 +1750,12 @@ fn unpublishable_catalog_containers_are_rejected() { container, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; // UNKNOWN only ever comes out of a catalog: we keep none of the original JSON, so @@ -3502,6 +3624,12 @@ fn media_consumers_cancel_while_subscribing() { container: moq_container::default(), warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_publish_video_config(broadcast, &video) }, 0); let (audio_name, audio_codec) = ("audio", "opus"); @@ -3521,6 +3649,12 @@ fn media_consumers_cancel_while_subscribing() { has_jitter: false, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_publish_audio_config(broadcast, &audio) }, 0); @@ -4993,6 +5127,12 @@ fn local_publish_consume() { has_jitter: false, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id, 0, &mut audio_cfg) }, 0); assert_eq!(audio_cfg.sample_rate, 48000); @@ -5022,6 +5162,12 @@ fn local_publish_consume() { container: moq_container::default(), warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert!( unsafe { moq_consume_video_config(catalog_id, 0, &mut video_cfg) } < 0, @@ -5115,6 +5261,12 @@ fn follow_local() { has_jitter: false, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id, 0, &mut audio_cfg) }, 0); assert_eq!(audio_cfg.sample_rate, 48000); @@ -5178,6 +5330,12 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { has_jitter: false, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_publish_audio_config(broadcast, &config) }, 0); @@ -5641,6 +5799,12 @@ fn video_publish_consume() { container: moq_container::default(), warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!( unsafe { moq_consume_video_config(catalog_id, 0, &mut video_cfg) }, @@ -5679,6 +5843,12 @@ fn video_publish_consume() { has_jitter: false, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert!( unsafe { moq_consume_audio_config(catalog_id, 0, &mut audio_cfg) } < 0, @@ -6798,6 +6968,12 @@ fn catalog_update_on_new_track() { has_jitter: false, warmup_us: 0, has_warmup: false, + broadcast: std::ptr::null(), + broadcast_len: 0, + instance: std::ptr::null(), + instance_len: 0, + track: std::ptr::null(), + track_len: 0, }; assert_eq!(unsafe { moq_consume_audio_config(catalog_id1, 0, &mut audio_cfg) }, 0); assert!(unsafe { moq_consume_audio_config(catalog_id1, 1, &mut audio_cfg) } < 0); From 451723388171a3db1fe2a9542f8834e1c6647efa Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 12:39:08 -0800 Subject: [PATCH 07/16] wip(moq-c): docs for the new bindings, formatting Co-Authored-By: Claude Opus 5.5 --- doc/lib/c/index.md | 2 +- doc/lib/index.md | 2 +- rs/moq-c/README.md | 49 +++++++++++++++++++++++++++++++++ rs/moq-c/src/api.rs | 36 ++++++++++++++++++++----- rs/moq-c/src/auth.rs | 5 +++- rs/moq-c/src/client.rs | 5 +++- rs/moq-c/src/lib.rs | 2 +- rs/moq-c/src/publish.rs | 25 ++++++++++++++--- rs/moq-c/src/session.rs | 4 ++- rs/moq-c/src/socket.rs | 52 +++++++++++++++++++++++++++++------ rs/moq-c/src/state.rs | 2 +- rs/moq-c/src/test.rs | 15 ++++++++--- rs/moq-c/src/test/parity.rs | 54 ++++++++++++++++++++++++++++++------- 13 files changed, 215 insertions(+), 38 deletions(-) diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index ebb435ee7d7..fe558688b1e 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -105,7 +105,7 @@ inside. The header is the reference: each function carries a doc comment. - **Handles and callbacks.** Every object is an integer handle, and every async result arrives on a `moq_status_callback` with your `void *user_data`. A status `> 0` is a live result, `0` a clean close, and `< 0` an error. The last two are terminal: moq-c never touches `user_data` again, so free it there. `*_close` and `*_cancel` only request shutdown; the terminal callback still fires. A session reports on a `moq_state_callback` instead: each `moq_connection_state` carries its `phase`, `connects`, the negative `failure` of the latest attempt, and the live `protocol`, and the `MOQ_CONNECTION_PHASE_CLOSED` snapshot is terminal, delivered after the handle is released. `moq_session_close()` drains finished tracks for dialed and accepted sessions; wait for that terminal snapshot to learn the result. - **Errors.** Negative return codes are named by `MOQ_ERROR_*`, and `moq_error()` gives the reason on the calling thread. Auth rejections have their own codes so you don't retry them. For the peer's protocol code use `moq_error_protocol()`; do not parse `moq_error()`. A panic in a binding background task reports `MOQ_ERROR_PANIC` through its terminal callback; unrelated objects keep running. A session closed because its credential expired has kind `MOQ_PROTOCOL_KIND_EXPIRED`, and a request refused for an expired token returns `MOQ_ERROR_EXPIRED`; refresh the token before retrying. Malformed credentials report `MOQ_PROTOCOL_KIND_MALFORMED_AUTH_TOKEN`; correct the token before reconnecting with it. A catalog that needs a newer moq-hang draft than this build reads returns `MOQ_ERROR_UNSUPPORTED_CATALOG`; upgrade the library to read it. A request-cap closure has kind `MOQ_PROTOCOL_KIND_TOO_MANY_REQUESTS`; reduce the workload or adjust the relay's [session limits](/bin/relay/config#session-and-peer) before reconnecting. -- **Tokens.** Set `moq_client_config.tokens` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. To replace expiring tokens, close the session and connect again. +- **Tokens.** Set `moq_client_config.tokens` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. Replace expiring tokens on the live session with `moq_session_tokens_set()`, learn the verdict from `moq_session_tokens_answered()`, and follow what the peer granted with `moq_session_grants()`. - **Threading.** Call any function from any thread. Callbacks run on moq-c's runtime thread; the callback and its `user_data` must be safe to use there. Synchronize access to data shared with other threads, and dispatch UI work to your UI thread. Raw publish calls block until the codec takes the frame, which paces a publisher. - **Zeroed config is the default.** A zeroed `moq_client_config` means the default for every field, so new fields don't break callers. A field whose default isn't zero has a `has_*` flag: `backoff_timeout_us = 0` means "retry forever" only with `has_backoff_timeout = true`. - **Subscription defaults.** A zeroed `moq_subscription`, a NULL pointer, and `moq_subscription_defaults()` all mean moq-net's defaults, whose zero `delay` starts at the newest group and skips a superseded one at once. Set `delay.max_unlimited` for no subscriber limit, and `delay.min_unstated` to leave the target latency unstated. diff --git a/doc/lib/index.md b/doc/lib/index.md index 7fdd728562b..eb8b791553b 100644 --- a/doc/lib/index.md +++ b/doc/lib/index.md @@ -77,7 +77,7 @@ how it looks in that language: - **Connection stats** and **errors** that tell an auth rejection (don't retry) from a shutdown or a transport failure. - **Authorization in band**: read the grant the relay sent back (the patterns this side may publish and subscribe to, and when it lapses), and present a fresh token before the current one expires, without reconnecting. It needs `moq-lite-07-wip`, which is opt-in, or moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth). -C's audio decoder takes a playout delay only as the floor `moq_delay.min_us` under its estimate, and reports none; C has no in-band authorization. +C cannot fetch a single group by sequence. ## Upgrading diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index 16a4dfbc4b6..f42531cc11a 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -47,6 +47,14 @@ int32_t moq_viewer_rate(uint32_t viewer, uint64_t *bps, bool *present); int32_t moq_viewer_update(uint32_t viewer, uint64_t max_bps); int32_t moq_viewer_close(uint32_t viewer); +// Session: Auth (a dialed session's tokens, and the grant the peer answers with) +int32_t moq_session_tokens_set(uint32_t session, const moq_string *tokens, uintptr_t tokens_len); +int32_t moq_session_tokens_answered(uint32_t session, moq_status_callback on_answer, void *user_data); +int32_t moq_session_grants(uint32_t session, moq_status_callback on_grant, void *user_data); +int32_t moq_session_grants_cancel(uint32_t watcher); +int32_t moq_grant_info(uint32_t grant, moq_grant *dst); +int32_t moq_grant_free(uint32_t grant); + // Server int32_t moq_server_listen(const moq_server_config *config, moq_status_callback on_request, void *user_data); int32_t moq_server_addr(uint32_t server, moq_string *dst); @@ -101,7 +109,12 @@ int32_t moq_publish_track_group(uint32_t track); int32_t moq_publish_track_frame(uint32_t track, const uint8_t *payload, uintptr_t payload_size, const moq_timestamp *timestamp); int32_t moq_publish_group_frame(uint32_t group, const uint8_t *payload, uintptr_t payload_size, const moq_timestamp *timestamp); int32_t moq_publish_group_finish(uint32_t group); +int32_t moq_publish_group_ready(uint32_t group, uint64_t size, moq_status_callback on_ready, void *user_data); int32_t moq_publish_track_finish(uint32_t track); +int32_t moq_publish_track_largest(uint32_t track, uint64_t *group, uint64_t *frame, bool *present); +int32_t moq_publish_timebase(uint32_t broadcast); +int32_t moq_publish_timebase_free(uint32_t timebase); +// moq_container_init.timebase (0 for none) shares one source clock across containers. // Publishing: Demand int32_t moq_publish_track_demand(uint32_t track, moq_status_callback on_demand, void *user_data); @@ -131,6 +144,8 @@ int32_t moq_group_request_free(uint32_t request); // Consuming int32_t moq_consume_close(uint32_t consume); +int32_t moq_consume_closed(uint32_t broadcast, moq_status_callback on_closed, void *user_data); +int32_t moq_consume_closed_cancel(uint32_t watcher); // Consuming: Catalog int32_t moq_consume_catalog(uint32_t broadcast, moq_status_callback on_catalog, void *user_data); @@ -157,6 +172,40 @@ int32_t moq_consume_track(uint32_t broadcast, const char *name, uintptr_t name_l int32_t moq_consume_track_frame(uint32_t frame, moq_frame *dst); int32_t moq_consume_track_frame_free(uint32_t frame); int32_t moq_consume_track_cancel(uint32_t track); + +// Sockets: two-way sessions between endpoints sharing an origin +int32_t moq_socket_create(uint32_t origin, const char *prefix, uintptr_t prefix_len, const char *id, uintptr_t id_len); +int32_t moq_socket_close(uint32_t endpoint); +int32_t moq_socket_dial_tcp(uint32_t endpoint, const char *peer, uintptr_t peer_len, moq_status_callback on_stream, void *user_data); +int32_t moq_socket_dial_track(uint32_t endpoint, const char *peer, uintptr_t peer_len, const moq_track_info *info, moq_status_callback on_stream, void *user_data); +int32_t moq_socket_accept_tcp(uint32_t endpoint, moq_status_callback on_incoming, void *user_data); +int32_t moq_socket_accept_track(uint32_t endpoint, moq_status_callback on_incoming, void *user_data); +int32_t moq_socket_cancel(uint32_t task); +int32_t moq_socket_incoming_info(uint32_t incoming, moq_string *peer, moq_string *session); +int32_t moq_socket_incoming_accept(uint32_t incoming, const moq_track_info *info, moq_status_callback on_stream, void *user_data); +int32_t moq_socket_incoming_reject(uint32_t incoming); +int32_t moq_socket_stream_info(uint32_t stream, moq_string *peer, moq_string *session); +int32_t moq_socket_stream_writer(uint32_t stream); // a group (tcp) or raw track (track) handle +int32_t moq_socket_stream_reader(uint32_t stream, moq_status_callback on_frame, void *user_data); // read like moq_consume_track +int32_t moq_socket_stream_free(uint32_t stream); + +// Codecs without a broadcast: encode, then publish or store the packets yourself +int32_t moq_audio_encoder_create(const moq_audio_encoder_output *output); +int32_t moq_audio_encoder_frame_size(uint32_t encoder); +int32_t moq_audio_encoder_init(uint32_t encoder, moq_audio_init *dst); +int32_t moq_audio_encoder_bitrate(uint32_t encoder, uint64_t bitrate); +int32_t moq_audio_encoder_encode(uint32_t encoder, const float *pcm, uintptr_t pcm_len); +int32_t moq_audio_encoder_finish(uint32_t encoder, const float *pcm, uintptr_t pcm_len, uint64_t *discard_padding); +int32_t moq_audio_encoder_packet(uint32_t encoder, uint32_t index, moq_frame *dst); +int32_t moq_audio_encoder_free(uint32_t encoder); +int32_t moq_video_encoder_create(const moq_video_encoder_input *input, const moq_video_encoder_output *output); +int32_t moq_video_encoder_encode(uint32_t encoder, const moq_video_encoder_frame *frame); +int32_t moq_video_encoder_cut(uint32_t encoder); +int32_t moq_video_encoder_bitrate(uint32_t encoder, uint64_t bitrate); +int32_t moq_video_encoder_flush(uint32_t encoder); +int32_t moq_video_encoder_finish(uint32_t encoder); +int32_t moq_video_encoder_packet(uint32_t encoder, uint32_t index, moq_frame *dst); +int32_t moq_video_encoder_free(uint32_t encoder); ``` Raw track frames use the same `moq_frame` record as media frames. Timestamps diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 95330886e3b..e06fdf93f61 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -1887,7 +1887,8 @@ pub(crate) unsafe fn parse_server(config: &moq_server_config) -> Result Result 0).then_some(config.coded_width); video.coded_height = (config.coded_height > 0).then_some(config.coded_height); video.container = unsafe { parse_container(&config.container)? }; - video.warmup = config.has_warmup.then(|| std::time::Duration::from_micros(config.warmup_us)); + video.warmup = config + .has_warmup + .then(|| std::time::Duration::from_micros(config.warmup_us)); (video.broadcast, video.instance, video.track) = unsafe { parse_reference( (config.broadcast, config.broadcast_len), @@ -3155,7 +3161,14 @@ unsafe fn parse_reference( broadcast: (*const c_char, usize), instance: (*const c_char, usize), track: (*const c_char, usize), -) -> Result<(Option, Option, Option), Error> { +) -> Result< + ( + Option, + Option, + Option, + ), + Error, +> { let broadcast = unsafe { ffi::parse_str_optional(broadcast.0, broadcast.1)? } .filter(|broadcast| !broadcast.is_empty()) .map(moq_net::path::Relative::new) @@ -3213,8 +3226,12 @@ pub unsafe extern "C" fn moq_publish_audio_config(broadcast: u32, config: *const let description = unsafe { ffi::parse_slice(config.description, config.description_len)? }; audio.description = Some(bytes::Bytes::copy_from_slice(description)); } - audio.jitter = config.has_jitter.then(|| std::time::Duration::from_micros(config.jitter_us)); - audio.warmup = config.has_warmup.then(|| std::time::Duration::from_micros(config.warmup_us)); + audio.jitter = config + .has_jitter + .then(|| std::time::Duration::from_micros(config.jitter_us)); + audio.warmup = config + .has_warmup + .then(|| std::time::Duration::from_micros(config.warmup_us)); (audio.broadcast, audio.instance, audio.track) = unsafe { parse_reference( (config.broadcast, config.broadcast_len), @@ -3475,7 +3492,12 @@ pub extern "C" fn moq_publish_track_finish_at(track: u32, final_sequence: u64) - /// # Safety /// - `group`, `frame`, and `present` must point at writable values. #[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_publish_track_largest(track: u32, group: *mut u64, frame: *mut u64, present: *mut bool) -> i32 { +pub unsafe extern "C" fn moq_publish_track_largest( + track: u32, + group: *mut u64, + frame: *mut u64, + present: *mut bool, +) -> i32 { ffi::enter(move || { let track = ffi::parse_id(track)?; let group = unsafe { group.as_mut() }.ok_or(Error::InvalidPointer)?; diff --git a/rs/moq-c/src/auth.rs b/rs/moq-c/src/auth.rs index ae9883324ce..305eabbc4a0 100644 --- a/rs/moq-c/src/auth.rs +++ b/rs/moq-c/src/auth.rs @@ -33,7 +33,10 @@ impl GrantRecord { fn new(grant: Option) -> Self { let patterns = |patterns: &moq_net::Patterns| patterns.iter().map(ToString::to_string).collect::>(); let publish = grant.as_ref().map(|grant| patterns(&grant.publish)).unwrap_or_default(); - let subscribe = grant.as_ref().map(|grant| patterns(&grant.subscribe)).unwrap_or_default(); + let subscribe = grant + .as_ref() + .map(|grant| patterns(&grant.subscribe)) + .unwrap_or_default(); let views = |strings: &[String]| { strings .iter() diff --git a/rs/moq-c/src/client.rs b/rs/moq-c/src/client.rs index edd35cd2cb6..4e522c73b79 100644 --- a/rs/moq-c/src/client.rs +++ b/rs/moq-c/src/client.rs @@ -179,7 +179,10 @@ pub unsafe fn parse_client(config: Option<&moq_client_config>) -> Result Result<(), Error> { let group = self.groups.get(group).ok_or(Error::GroupNotFound)?; let mut group = group.inner.lock(); - group.as_mut().ok_or(Error::GroupNotFound)?.write_frame(timestamp, bytes::Bytes::copy_from_slice(payload))?; + group + .as_mut() + .ok_or(Error::GroupNotFound)? + .write_frame(timestamp, bytes::Bytes::copy_from_slice(payload))?; Ok(()) } @@ -1488,21 +1491,35 @@ impl Publish { pub fn group( &self, group: Id, - ) -> Result<(crate::state::Shared, tokio::sync::watch::Receiver<()>), Error> { + ) -> Result< + ( + crate::state::Shared, + tokio::sync::watch::Receiver<()>, + ), + Error, + > { let entry = self.groups.get(group).ok_or(Error::GroupNotFound)?; Ok((entry.inner.clone(), entry.ended.subscribe())) } /// Finish a raw group. No more frames can be written. pub fn group_finish(&mut self, group: Id) -> Result<(), Error> { - let mut group = self.groups.remove(group).and_then(|group| group.inner.take()).ok_or(Error::GroupNotFound)?; + let mut group = self + .groups + .remove(group) + .and_then(|group| group.inner.take()) + .ok_or(Error::GroupNotFound)?; group.finish()?; Ok(()) } /// Abort a raw group with an application error code. pub fn group_abort(&mut self, group: Id, error_code: u16) -> Result<(), Error> { - let group = self.groups.remove(group).and_then(|group| group.inner.take()).ok_or(Error::GroupNotFound)?; + let group = self + .groups + .remove(group) + .and_then(|group| group.inner.take()) + .ok_or(Error::GroupNotFound)?; group.abort(moq_net::Error::App(error_code))?; Ok(()) } diff --git a/rs/moq-c/src/session.rs b/rs/moq-c/src/session.rs index 413b53c1b26..c26e8236094 100644 --- a/rs/moq-c/src/session.rs +++ b/rs/moq-c/src/session.rs @@ -323,7 +323,9 @@ impl Session { pub fn tokens(&self, id: Id) -> Result { match self.link(id)? { Link::Dialed { connection, .. } => Ok(connection.tokens()), - Link::Accepted(_) => Err(Error::Unsupported("a server-accepted session presents no tokens".into())), + Link::Accepted(_) => Err(Error::Unsupported( + "a server-accepted session presents no tokens".into(), + )), } } diff --git a/rs/moq-c/src/socket.rs b/rs/moq-c/src/socket.rs index 6eafcd697b1..390744a6d0c 100644 --- a/rs/moq-c/src/socket.rs +++ b/rs/moq-c/src/socket.rs @@ -125,8 +125,18 @@ impl Socket { }) } - fn dial(&mut self, endpoint: Id, peer: &str, track: Option>, callback: OnStatus) -> Result { - let EndpointEntry { inner, driver, children } = self.endpoint(endpoint)?; + fn dial( + &mut self, + endpoint: Id, + peer: &str, + track: Option>, + callback: OnStatus, + ) -> Result { + let EndpointEntry { + inner, + driver, + children, + } = self.endpoint(endpoint)?; let (driver, children) = (driver.clone(), children.clone()); let watch = driver.clone(); let pending: std::pin::Pin> + Send>> = match track { @@ -147,7 +157,11 @@ impl Socket { } fn accept(&mut self, endpoint: Id, track: bool, callback: OnStatus) -> Result { - let EndpointEntry { inner, driver, children } = self.endpoint(endpoint)?; + let EndpointEntry { + inner, + driver, + children, + } = self.endpoint(endpoint)?; let (inner, driver, children) = (inner.clone(), driver.clone(), children.clone()); let poll = move |waiter: &kio::Waiter| match track { false => inner.poll_accept_tcp(waiter).map_ok(IncomingKind::Tcp), @@ -202,14 +216,22 @@ impl Socket { ) } - fn incoming_accept(&mut self, incoming: Id, info: Option, callback: OnStatus) -> Result { + fn incoming_accept( + &mut self, + incoming: Id, + info: Option, + callback: OnStatus, + ) -> Result { let entry = self.incoming.get(incoming).ok_or(Error::NotFound)?; entry.driver.check()?; if info.is_some() && matches!(entry.inner, IncomingKind::Tcp(_)) { return Err(Error::InvalidConfig("a tcp session has no track info".into())); } let IncomingEntry { - inner, driver, children, .. + inner, + driver, + children, + .. } = self.incoming.remove(incoming).ok_or(Error::NotFound)?; let watch = driver.clone(); let pending: std::pin::Pin> + Send>> = match inner { @@ -229,13 +251,23 @@ impl Socket { ) } - fn incoming_info(&self, incoming: Id, peer: Option<&mut moq_string>, session: Option<&mut moq_string>) -> Result<(), Error> { + fn incoming_info( + &self, + incoming: Id, + peer: Option<&mut moq_string>, + session: Option<&mut moq_string>, + ) -> Result<(), Error> { let entry = self.incoming.get(incoming).ok_or(Error::NotFound)?; write_ids(&entry.peer, &entry.session, peer, session); Ok(()) } - fn stream_info(&self, stream: Id, peer: Option<&mut moq_string>, session: Option<&mut moq_string>) -> Result<(), Error> { + fn stream_info( + &self, + stream: Id, + peer: Option<&mut moq_string>, + session: Option<&mut moq_string>, + ) -> Result<(), Error> { let entry = self.streams.get(stream).ok_or(Error::NotFound)?; write_ids(&entry.peer, &entry.session, peer, session); Ok(()) @@ -424,7 +456,11 @@ pub extern "C" fn moq_socket_cancel(task: u32) -> i32 { /// # Safety /// - `peer` and `session` must each be NULL or point at a writable [moq_string]. #[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_socket_incoming_info(incoming: u32, peer: *mut moq_string, session: *mut moq_string) -> i32 { +pub unsafe extern "C" fn moq_socket_incoming_info( + incoming: u32, + peer: *mut moq_string, + session: *mut moq_string, +) -> i32 { ffi::enter(move || { let incoming = ffi::parse_id(incoming)?; let (peer, session) = unsafe { (peer.as_mut(), session.as_mut()) }; diff --git a/rs/moq-c/src/state.rs b/rs/moq-c/src/state.rs index f15f5b2f03c..92743a9486a 100644 --- a/rs/moq-c/src/state.rs +++ b/rs/moq-c/src/state.rs @@ -1,9 +1,9 @@ use std::sync::{Arc, LazyLock, Mutex, MutexGuard, PoisonError}; use crate::auth::Auth; +use crate::bandwidth::Bandwidth; use crate::encoder::Encoders; use crate::socket::Socket; -use crate::bandwidth::Bandwidth; use crate::{Consume, Origin, Publish, Server, Session, audio::Audio, video::Video}; pub struct State { diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index d2c7b9f4a86..5d74c1d5cd9 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -1327,9 +1327,18 @@ fn publish_catalog_roundtrip() { assert_eq!(video_cfg.coded_height, 1080); assert_eq!((video_cfg.warmup_us, video_cfg.has_warmup), (250_000, true)); // Normalized: a reader sees the plain relative path. - assert_eq!(borrowed_string(video_cfg.broadcast, video_cfg.broadcast_len).as_deref(), Some("source")); - assert_eq!(borrowed_string(video_cfg.instance, video_cfg.instance_len), Some(instance.clone())); - assert_eq!(borrowed_string(video_cfg.track, video_cfg.track_len).as_deref(), Some(track)); + assert_eq!( + borrowed_string(video_cfg.broadcast, video_cfg.broadcast_len).as_deref(), + Some("source") + ); + assert_eq!( + borrowed_string(video_cfg.instance, video_cfg.instance_len), + Some(instance.clone()) + ); + assert_eq!( + borrowed_string(video_cfg.track, video_cfg.track_len).as_deref(), + Some(track) + ); let mut enabled = std::mem::MaybeUninit::::uninit(); assert_eq!( unsafe { moq_consume_video_enabled(catalog_id, 0, enabled.as_mut_ptr()) }, diff --git a/rs/moq-c/src/test/parity.rs b/rs/moq-c/src/test/parity.rs index 12421f8b220..b721bbae933 100644 --- a/rs/moq-c/src/test/parity.rs +++ b/rs/moq-c/src/test/parity.rs @@ -59,7 +59,10 @@ fn connect(a: u32, b: u32, track: bool) -> (u32, u32, [Callback; 3]) { let incoming = id(accepts.recv()); let (mut claimed, mut session) = (moq_str(""), moq_str("")); - assert_eq!(unsafe { moq_socket_incoming_info(incoming, &mut claimed, &mut session) }, 0); + assert_eq!( + unsafe { moq_socket_incoming_info(incoming, &mut claimed, &mut session) }, + 0 + ); assert_eq!(lent(claimed), "a"); let accepted = Callback::new(); let _accepting = @@ -86,10 +89,20 @@ fn socket_tcp_round_trip() { assert_eq!(unsafe { moq_socket_stream_info(client, &mut peer, &mut session) }, 0); assert_eq!(lent(peer), "b"); let client_session = lent(session); - assert_eq!(unsafe { moq_socket_stream_info(server, &mut peer, std::ptr::null_mut()) }, 0); + assert_eq!( + unsafe { moq_socket_stream_info(server, &mut peer, std::ptr::null_mut()) }, + 0 + ); assert_eq!(lent(peer), "a"); - assert_eq!(unsafe { moq_socket_stream_info(server, std::ptr::null_mut(), &mut session) }, 0); - assert_eq!(lent(session), client_session, "both sides share the dialer's session id"); + assert_eq!( + unsafe { moq_socket_stream_info(server, std::ptr::null_mut(), &mut session) }, + 0 + ); + assert_eq!( + lent(session), + client_session, + "both sides share the dialer's session id" + ); let writer = id(moq_socket_stream_writer(client)); assert!(moq_socket_stream_writer(client) < 0, "the writer is taken once"); @@ -151,7 +164,10 @@ fn socket_track_round_trip_and_endpoint_close() { // Closing the endpoint ends its open track halves. assert_eq!(moq_socket_close(a), 0); - assert!(moq_publish_track_finish(track) < 0, "the endpoint's close released the track"); + assert!( + moq_publish_track_finish(track) < 0, + "the endpoint's close released the track" + ); assert!(frames.recv_terminal() < 0, "the peer's half reset"); assert_eq!(moq_socket_stream_free(client), 0); @@ -174,13 +190,24 @@ fn socket_reject_and_cancel() { id(unsafe { moq_socket_dial_tcp(a, peer.as_ptr().cast(), peer.len(), Some(channel_callback), dialed.ptr) }); let incoming = id(accepts.recv()); assert_eq!(moq_socket_incoming_reject(incoming), 0); - assert!(moq_socket_incoming_reject(incoming) < 0, "rejecting releases the handle"); + assert!( + moq_socket_incoming_reject(incoming) < 0, + "rejecting releases the handle" + ); assert!(dialed.recv_terminal() < 0, "a rejected dial fails"); // Dialing oneself is refused at once. let me = "a"; assert_eq!( - unsafe { moq_socket_dial_tcp(a, me.as_ptr().cast(), me.len(), Some(ignore_callback), std::ptr::null_mut()) }, + unsafe { + moq_socket_dial_tcp( + a, + me.as_ptr().cast(), + me.len(), + Some(ignore_callback), + std::ptr::null_mut(), + ) + }, MOQ_ERROR_UNSUPPORTED ); @@ -188,7 +215,13 @@ fn socket_reject_and_cancel() { let waiting = Callback::new(); let absent = "nobody"; let dial = id(unsafe { - moq_socket_dial_tcp(a, absent.as_ptr().cast(), absent.len(), Some(channel_callback), waiting.ptr) + moq_socket_dial_tcp( + a, + absent.as_ptr().cast(), + absent.len(), + Some(channel_callback), + waiting.ptr, + ) }); assert_eq!(moq_socket_cancel(dial), 0); assert_eq!(waiting.recv_terminal(), 0); @@ -354,7 +387,10 @@ fn session_tokens_and_grants() { unsafe { moq_session_tokens_set(client, empty.as_ptr(), empty.len()) }, MOQ_ERROR_INVALID_CONFIG ); - assert_eq!(unsafe { moq_session_tokens_set(client, token.as_ptr(), token.len()) }, 0); + assert_eq!( + unsafe { moq_session_tokens_set(client, token.as_ptr(), token.len()) }, + 0 + ); // The grant is delivered at once; the default protocol carries no AUTH, so it stays absent. let grants = Callback::new(); From 4a38bdce6d5c73fbc77d060ff8e6ef79a2d60f7a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 12:52:09 -0800 Subject: [PATCH 08/16] wip(moq-c): lint fixes Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/api.rs | 16 ++++++++-------- rs/moq-c/src/consume.rs | 2 +- rs/moq-c/src/socket.rs | 4 ++-- rs/moq-c/src/test/parity.rs | 4 ++++ 4 files changed, 15 insertions(+), 11 deletions(-) diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index e06fdf93f61..37b76e72f96 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -3153,6 +3153,13 @@ pub unsafe extern "C" fn moq_publish_video_config(broadcast: u32, config: *const }) } +/// A rendition's broadcast reference, instance, and track name. +type Reference = ( + Option, + Option, + Option, +); + /// A rendition's reference fields, as [moq_video_config] and [moq_audio_config] carry them. /// /// # Safety @@ -3161,14 +3168,7 @@ unsafe fn parse_reference( broadcast: (*const c_char, usize), instance: (*const c_char, usize), track: (*const c_char, usize), -) -> Result< - ( - Option, - Option, - Option, - ), - Error, -> { +) -> Result { let broadcast = unsafe { ffi::parse_str_optional(broadcast.0, broadcast.1)? } .filter(|broadcast| !broadcast.is_empty()) .map(moq_net::path::Relative::new) diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index 7dc13e82902..9bdd352564a 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -930,7 +930,7 @@ impl Consume { tokio::spawn(async move { let res = crate::ffi::run(driver.watch(async move { match half { - crate::socket::Half::Track(track) => Self::run_raw(on_frame, track.ordered(), close).await, + crate::socket::Half::Track(track) => Self::run_raw(on_frame, (*track).ordered(), close).await, crate::socket::Half::Group(mut group) => { Self::run_group(on_frame, &mut group, &mut close).await.map(drop) } diff --git a/rs/moq-c/src/socket.rs b/rs/moq-c/src/socket.rs index 390744a6d0c..63ba2ecd8fd 100644 --- a/rs/moq-c/src/socket.rs +++ b/rs/moq-c/src/socket.rs @@ -47,7 +47,7 @@ struct IncomingEntry { /// The peer's half of a stream, read through [Consume](crate::Consume). pub(crate) enum Half { - Track(moq_net::track::Subscriber), + Track(Box), Group(moq_net::group::Consumer), } @@ -85,7 +85,7 @@ impl StreamEntry { peer, session, writer: Some(Writer::Track(stream.producer)), - reader: Some(Half::Track(stream.consumer)), + reader: Some(Half::Track(Box::new(stream.consumer))), driver, children, } diff --git a/rs/moq-c/src/test/parity.rs b/rs/moq-c/src/test/parity.rs index b721bbae933..6ce100c7b0c 100644 --- a/rs/moq-c/src/test/parity.rs +++ b/rs/moq-c/src/test/parity.rs @@ -291,6 +291,10 @@ fn track_largest_and_group_ready() { ); // Let the wait park first: finishing must still end it, though moq-net does not wake // `poll_ready` on a finish. + #[expect( + clippy::disallowed_methods, + reason = "the test thread has no runtime; it gives the C API's runtime time to park the wait" + )] std::thread::sleep(Duration::from_millis(50)); assert_eq!(moq_publish_group_finish(first), 0); assert_eq!(ready.rx.recv_timeout(Duration::from_secs(2)), Ok(0)); From d051c869dc102aa032223ba2cab991b5fd2371af Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 13:00:03 -0800 Subject: [PATCH 09/16] wip(moq-c): README cites current consume read calls Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index f42531cc11a..873d3374084 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -165,8 +165,8 @@ int32_t moq_consume_audio(uint32_t catalog, uint32_t index, const moq_delay *del int32_t moq_consume_audio_cancel(uint32_t track); // Consuming: Frames -int32_t moq_consume_frame(uint32_t frame, moq_frame *dst); -int32_t moq_consume_frame_free(uint32_t frame); +int32_t moq_consume_read(uint32_t read, moq_media_read *dst); +int32_t moq_consume_read_free(uint32_t read); moq_subscription moq_subscription_defaults(void); int32_t moq_consume_track(uint32_t broadcast, const char *name, uintptr_t name_len, const moq_subscription *subscription, moq_status_callback on_frame, void *user_data); int32_t moq_consume_track_frame(uint32_t frame, moq_frame *dst); From d7fce3064b7085942842b04f2fb714280cb5202e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 13:01:22 -0800 Subject: [PATCH 10/16] chore(quest): finish quest/m2/cut-gate/c/README.md Co-Authored-By: Claude Opus 5.5 --- quest/m2/cut-gate/README.md | 1 - quest/m2/cut-gate/c/README.md | 32 -------------------------------- quest/m3/c/README.md | 2 +- quest/m3/c/consumers.md | 2 +- quest/m5/c-origin-relay.md | 4 ---- 5 files changed, 2 insertions(+), 39 deletions(-) delete mode 100644 quest/m2/cut-gate/c/README.md diff --git a/quest/m2/cut-gate/README.md b/quest/m2/cut-gate/README.md index dc212688434..7d9aff7fc90 100644 --- a/quest/m2/cut-gate/README.md +++ b/quest/m2/cut-gate/README.md @@ -34,4 +34,3 @@ stays in m1 until its claim merges, so this gate lists it as a blocker; the - [Pre-cut audit findings](/quest/m2/cut-gate/cut-audit/README.md) - fix the crashes, hostile-input costs, and correctness bugs the 2026-10-24 audit of main found - [Main is no slower than release](/quest/m1/release-perf/README.md) - every benchmark where main is slower than release is fixed or accepted with a reason (held in m1 by an open claim) -- [moq-c at parity](/quest/m2/cut-gate/c/README.md) - the hand-written `moq-c` ships at the cut with every binding feature moq-ffi gains diff --git a/quest/m2/cut-gate/c/README.md b/quest/m2/cut-gate/c/README.md deleted file mode 100644 index 0d4a3133999..00000000000 --- a/quest/m2/cut-gate/c/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# [M] moq-c at parity for the cut - -## Goal - -The hand-written `moq-c` crate (`rs/moq-c`, `moq.h`) ships at this cut at the -shared 0.22 minor with every binding feature moq-ffi gains in m1 or m2, so a C user -can do whatever a Python, Swift, Kotlin, Go, Dart, or C++ user can. The C -interop client and every `doc/lib/c` sample build and run against the built -release archive before the cut. - -## Plan - -Decided 2026-10-25 (maintainer): the hand-written crate ships at this cut and -the [generated C line](/quest/m3/c/README.md) moves after it, waiting on the -switch to rust2's UniFFI fork. The generated package (`c/moq`) builds in CI, -but it publishes only after the cut. C users break -twice (to 0.22 at this cut, then to the generated package at a later cut); -that is the accepted cost. moq-c follows the shared minor like every -published package (CONTRIBUTING.md's [Versions](/CONTRIBUTING.md#versions), -[moq-dev/moq#7610](https://github.com/moq-dev/moq/pull/7610)), not a 0.7 -then 0.8 line of its own. - -- moq-c is not frozen: it takes the same breaks as moq-ffi and the other - bindings. Every m1 or m2 quest or PR that changes the binding API changes - `rs/moq-c` in the same PR, with its Impact migration note and `doc/lib/c` - update; none waits on the generated package. -- Before the cut, diff the moq-ffi exports against `moq.h` and add any m1 or m2 - binding feature still missing, so parity is checked rather than assumed. -- `rs/moq-c` publishes through release-plz like the other crates; confirm the - release produces the C archive the samples are checked against. - -Public API: moq-c gains each m1 or m2 binding feature. Wire: none. diff --git a/quest/m3/c/README.md b/quest/m3/c/README.md index b64669c313c..1fc17ffcc07 100644 --- a/quest/m3/c/README.md +++ b/quest/m3/c/README.md @@ -12,7 +12,7 @@ scope; they already sit on moq-ffi through the generated C++. Decided 2026-10-25 (maintainer): this line ships after the cut, once moq builds its bindings from rust2's UniFFI fork. The hand-written crate ships at the cut -with [parity](/quest/m2/cut-gate/c/README.md) instead. The generator fix for the C name +with parity ([moq-dev/moq#8060](https://github.com/moq-dev/moq/pull/8060)) instead. The generator fix for the C name clash landed in rust2's fork ([moq-dev/rust2#66](https://github.com/moq-dev/rust2/pull/66)), not in a `kixelated/uniffi-bindgen-cpp` release, and reaches moq with the switch. diff --git a/quest/m3/c/consumers.md b/quest/m3/c/consumers.md index 3bdf1f7cbec..bd0f5602c13 100644 --- a/quest/m3/c/consumers.md +++ b/quest/m3/c/consumers.md @@ -21,7 +21,7 @@ the smoke client (`test/smoke/clients/c`), which callbacks on the host's own loop through `moq_set_dispatcher`. Waits for the cut and the generator switch (found when first started, -2026-10-28; decided 2026-10-31). Until the cut, [moq-c parity](/quest/m2/cut-gate/c/README.md) ships the +2026-10-28; decided 2026-10-31). Until the cut, moq-c parity ([moq-dev/moq#8060](https://github.com/moq-dev/moq/pull/8060)) ships the hand-written crate at 0.22 and proves it with this interop client and the current `doc/lib/c`, and `doc/` describes only what ships, so either half landing first drops the shipping crate's proof and documents an unpublished API. The switch diff --git a/quest/m5/c-origin-relay.md b/quest/m5/c-origin-relay.md index 4966c5106e8..62fda7a9c9d 100644 --- a/quest/m5/c-origin-relay.md +++ b/quest/m5/c-origin-relay.md @@ -28,7 +28,3 @@ watcher. Public API: additive in moq-c, or in moq-ffi if the generated C line has replaced it. Wire: none. - -## Related - -- [moq-c at parity](/quest/m2/cut-gate/c/README.md) - the hand-written crate's pre-cut parity work, which this does not block From 4a486d057aff09fb4de1aaeda161ee02c4546867 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 13:07:07 -0800 Subject: [PATCH 11/16] fix(moq-c): a surface decode pins VideoToolbox and skips CPU validation Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/test/parity.rs | 11 +++++++++++ rs/moq-c/src/video.rs | 25 ++++++++++++++++++------- 2 files changed, 29 insertions(+), 7 deletions(-) diff --git a/rs/moq-c/src/test/parity.rs b/rs/moq-c/src/test/parity.rs index 6ce100c7b0c..e477d653818 100644 --- a/rs/moq-c/src/test/parity.rs +++ b/rs/moq-c/src/test/parity.rs @@ -532,4 +532,15 @@ fn native_surfaces_are_unsupported_off_apple() { unsafe { moq_decode_video(1, 0, &output, Some(ignore_callback), std::ptr::null_mut()) }, MOQ_ERROR_UNSUPPORTED ); + // A surface ignores the CPU layout and size, so an odd size is not the refusal. + let odd = moq_video_decoder_output { + width: 641, + height: 481, + format: 999, + ..output + }; + assert_eq!( + unsafe { moq_decode_video(1, 0, &odd, Some(ignore_callback), std::ptr::null_mut()) }, + MOQ_ERROR_UNSUPPORTED + ); } diff --git a/rs/moq-c/src/video.rs b/rs/moq-c/src/video.rs index c317c2ffb9b..66a86856a3a 100644 --- a/rs/moq-c/src/video.rs +++ b/rs/moq-c/src/video.rs @@ -188,7 +188,8 @@ pub struct moq_video_decoder_output { /// Decode to the platform's own surface and hand it out as each frame's `surface`, /// skipping the CPU conversion: `format`, `width`, and `height` are then ignored and /// `data` is NULL. Only Apple platforms have one, an IOSurface-backed NV12 - /// `CVPixelBufferRef`; elsewhere [`moq_decode_video`] fails with `MOQ_ERROR_UNSUPPORTED`. + /// `CVPixelBufferRef` from VideoToolbox, with no software fallback; elsewhere + /// [`moq_decode_video`] fails with `MOQ_ERROR_UNSUPPORTED`. pub surface: bool, } @@ -1234,8 +1235,14 @@ pub unsafe extern "C" fn moq_decode_video( // Validate the request before resolving anything: a C caller can probe // support without a live track, and a bad request never opens a // subscription it would immediately drop. - let format = pixel_format_from_u32(raw.format)?; - let size = decoder_size(raw.width, raw.height)?; + if raw.surface && !HAS_SURFACE { + return Err(Error::Unsupported("no decoder surface on this platform".into())); + } + // A surface decode converts nothing, so its CPU layout and size go unread. + let (format, size) = match raw.surface { + true => (moq_video_pixel_format::MOQ_VIDEO_PIXEL_FORMAT_I420, None), + false => (pixel_format_from_u32(raw.format)?, decoder_size(raw.width, raw.height)?), + }; let start = match moq_decode_start::from_u32(raw.start)? { moq_decode_start::MOQ_DECODE_START_OLDEST => moq_video::decode::Start::Oldest, moq_decode_start::MOQ_DECODE_START_LATEST => moq_video::decode::Start::Latest, @@ -1247,11 +1254,15 @@ pub unsafe extern "C" fn moq_decode_video( options.delay = raw.delay.into(); // A caller taking packed pixels lets a backend that can decode straight to the CPU do // that rather than downloading afterwards. - options.decoder.output = match (raw.surface, HAS_SURFACE) { - (false, _) => moq_video::Output::Cpu, - (true, true) => moq_video::Output::Native, - (true, false) => return Err(Error::Unsupported("no decoder surface on this platform".into())), + options.decoder.output = match raw.surface { + false => moq_video::Output::Cpu, + true => moq_video::Output::Native, }; + // Only VideoToolbox decodes into a `CVPixelBuffer`: a software fallback would hand out + // CPU pixels with neither `data` nor `surface` to read them by, so fail instead. + if raw.surface { + options.decoder.kind = moq_video::decode::Kind::Named("videotoolbox".into()); + } // A backend with a hardware scaler (NVDEC) honors this for free; the // delivery loop still enforces it, since other backends ignore it. options.decoder.scale_hint = size; From e2e4fa97462f8c0afad1f8c3782bfbfc2c386664 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 16:41:57 -0800 Subject: [PATCH 12/16] fix(moq-c): address review on the parity PR - Socket endpoints drop finished track producers instead of keeping them until close. - A grant watch ends with the session's failure reason instead of a clean 0. - Media consumers enforce a rendition's instance when resolving its broadcast. - A buffered first dial no longer escapes an accept loop's cancel. - Document live token replacement without AUTH, the parity scope, and group_ready across a broadcast close. Co-Authored-By: Claude Opus 5.5 --- doc/lib/c/index.md | 2 +- quest/m3/c/README.md | 5 +- rs/moq-c/src/api.rs | 4 +- rs/moq-c/src/auth.rs | 11 ++-- rs/moq-c/src/consume.rs | 33 ++++++---- rs/moq-c/src/publish.rs | 39 +++++++++-- rs/moq-c/src/socket.rs | 27 +++++--- rs/moq-c/src/test.rs | 82 +++++++++++++++-------- rs/moq-c/src/test/parity.rs | 125 ++++++++++++++++++++++++++++++++++++ 9 files changed, 267 insertions(+), 61 deletions(-) diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index dac387ce238..6849b86d54f 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -105,7 +105,7 @@ inside. The header is the reference: each function carries a doc comment. - **Handles and callbacks.** Every object is an integer handle, and every async result arrives on a `moq_status_callback` with your `void *user_data`. A status `> 0` is a live result, `0` a clean close, and `< 0` an error. The last two are terminal: moq-c never touches `user_data` again, so free it there. `*_close` and `*_cancel` only request shutdown; the terminal callback still fires. A session reports on a `moq_state_callback` instead: each `moq_connection_state` carries its `phase`, `connects`, the negative `failure` of the latest attempt, and the live `protocol`, and the `MOQ_CONNECTION_PHASE_CLOSED` snapshot is terminal, delivered after the handle is released. `moq_session_close()` drains finished tracks for dialed and accepted sessions; wait for that terminal snapshot to learn the result. - **Errors.** Negative return codes are named by `MOQ_ERROR_*`, and `moq_error()` gives the reason on the calling thread. Auth rejections have their own codes so you don't retry them. For the peer's protocol code use `moq_error_protocol()`; do not parse `moq_error()`. A panic in a binding background task reports `MOQ_ERROR_PANIC` through its terminal callback; unrelated objects keep running. A session closed because its credential expired has kind `MOQ_PROTOCOL_KIND_EXPIRED`, and a request refused for an expired token returns `MOQ_ERROR_EXPIRED`; refresh the token before retrying. Malformed credentials report `MOQ_PROTOCOL_KIND_MALFORMED_AUTH_TOKEN`; correct the token before reconnecting with it. A catalog that needs a newer moq-hang draft than this build reads returns `MOQ_ERROR_UNSUPPORTED_CATALOG`; upgrade the library to read it. A request-cap closure has kind `MOQ_PROTOCOL_KIND_TOO_MANY_REQUESTS`; reduce the workload or adjust the relay's [session limits](/bin/relay/config#session-and-peer) before reconnecting. -- **Tokens.** Set `moq_client_config.tokens` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. Replace expiring tokens on the live session with `moq_session_tokens_set()`, learn the verdict from `moq_session_tokens_answered()`, and follow what the peer granted with `moq_session_grants()`. +- **Tokens.** Set `moq_client_config.tokens` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. `moq_session_tokens_set()` replaces them before they expire: the next dial presents them, and a live AUTH session at once. A live session without AUTH (lite before 07, or moq-transport without the extension) keeps the old credential until it redials, and `moq_session_tokens_answered()` reports `MOQ_ERROR_UNSUPPORTED` for it. Otherwise that call reports the peer's verdict. Follow what the peer granted with `moq_session_grants()`. - **Threading.** Call any function from any thread. Callbacks run on moq-c's runtime thread; the callback and its `user_data` must be safe to use there. Synchronize access to data shared with other threads, and dispatch UI work to your UI thread. Raw publish calls block until the codec takes the frame, which paces a publisher. - **Zeroed config is the default.** A zeroed `moq_client_config` means the default for every field, so new fields don't break callers. A field whose default isn't zero has a `has_*` flag: `backoff_timeout_us = 0` means "retry forever" only with `has_backoff_timeout = true`. - **Subscription defaults.** A zeroed `moq_subscription`, a NULL pointer, and `moq_subscription_defaults()` all mean moq-net's defaults, whose zero `delay` starts at the newest group and skips a superseded one at once. Set `delay.max_unlimited` for no subscriber limit, and `delay.min_unstated` to leave the target latency unstated. diff --git a/quest/m3/c/README.md b/quest/m3/c/README.md index 1fc17ffcc07..d9e9e8e0ea1 100644 --- a/quest/m3/c/README.md +++ b/quest/m3/c/README.md @@ -12,7 +12,10 @@ scope; they already sit on moq-ffi through the generated C++. Decided 2026-10-25 (maintainer): this line ships after the cut, once moq builds its bindings from rust2's UniFFI fork. The hand-written crate ships at the cut -with parity ([moq-dev/moq#8060](https://github.com/moq-dev/moq/pull/8060)) instead. The generator fix for the C name +instead, with the binding features moq-ffi gained in m1 and m2 +([moq-dev/moq#8060](https://github.com/moq-dev/moq/pull/8060)). Features moq-c +never had, such as single-group fetch and group-level consumption, wait for this +line. The generator fix for the C name clash landed in rust2's fork ([moq-dev/rust2#66](https://github.com/moq-dev/rust2/pull/66)), not in a `kixelated/uniffi-bindgen-cpp` release, and reaches moq with the switch. diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 3d515891da9..7e14786fa1e 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -3876,7 +3876,9 @@ pub extern "C" fn moq_publish_group_finish(group: u32) -> i32 { /// the next write reports why; or a negative code. Wait before each [moq_publish_group_frame] /// and that reader paces the writer, instead of the group shedding frames it has not taken; /// slower readers are not waited on. Writing without waiting never fails; the group sheds its -/// front instead. +/// front instead. Closing the broadcast ends the group, and so the wait, unless its track +/// declared an end with [moq_publish_track_finish_at]: such a track still takes groups below +/// its end, so the wait lasts until a reader takes the group or the group ends. /// /// Returns zero once the wait started, or a negative code, in which case `on_ready` never fires. /// diff --git a/rs/moq-c/src/auth.rs b/rs/moq-c/src/auth.rs index 305eabbc4a0..c5af637d21e 100644 --- a/rs/moq-c/src/auth.rs +++ b/rs/moq-c/src/auth.rs @@ -104,8 +104,9 @@ impl Auth { _ = &mut close => return Ok(()), changed = kio::wait(|waiter| watch.poll_changed(waiter)) => match changed { Ok(grant) => grant, - // Nothing will change the grant again: the session ended. - Err(_) => return Ok(()), + // Nothing will change the grant again: the session closed, or failed. + Err(moq_net::Error::Cancel | moq_net::Error::Closed) => return Ok(()), + Err(err) => return Err(err.into()), }, }; } @@ -195,9 +196,9 @@ pub unsafe extern "C" fn moq_session_tokens_answered( /// Follow the grant a session's peer gave it: the union of every token the session presented. /// /// `on_grant` fires at once with a positive grant handle for the current grant, again with a -/// new handle on every change, then exactly once more with a terminal `0` once nothing will -/// change it (the session ended, or [moq_session_grants_cancel]) or a negative error; release -/// `user_data` there. Read each handle with [moq_grant_info] and release it with +/// new handle on every change, then exactly once more with a terminal code once nothing will +/// change it: `0` when the session closed or [moq_session_grants_cancel] stopped the watch, or +/// a negative error when the session failed. Release `user_data` there. Read each handle with [moq_grant_info] and release it with /// [moq_grant_free]. A dialed session's grant survives reconnects, reading not present while /// offline. AUTH is only on `moq-lite-07-wip` and on moq-transport sessions that negotiate the /// MoQ Auth extension; elsewhere the grant stays not present. diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index 9bdd352564a..f113d59487f 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -150,28 +150,34 @@ struct ConsumeBroadcast { origin: Option, } -/// The broadcast serving a rendition, honoring its catalog `broadcast` reference. +/// The broadcast serving a rendition, honoring its catalog `broadcast` reference and `instance`. /// -/// An absent or empty reference names the catalog's own broadcast, which the caller already -/// holds; anything else resolves against that broadcast's path through the origin, which -/// deduplicates the subscription the catalog itself already holds. Awaited inside the track -/// task, never under the state lock, so `origin` is cloned out rather than borrowed. +/// An absent or empty reference names the catalog's own broadcast; anything else resolves +/// against that broadcast's path through the origin, which deduplicates the subscription the +/// catalog itself already holds. A rendition naming an instance resolves through the origin +/// even without a reference, so a broadcast proven to serve another stream is refused; a route +/// over a wire that carries no instance cannot prove one, so there it is best effort. Awaited +/// inside the track task, never under the state lock, so `origin` is cloned out rather than +/// borrowed. async fn resolve( broadcast: moq_net::broadcast::Consumer, origin: Option, reference: Option, + instance: Option, ) -> Result { - let Some(reference) = reference.filter(|reference| !reference.is_empty()) else { + let reference = reference.filter(|reference| !reference.is_empty()); + // The catalog's own broadcast, with no instance to check, or none to prove: a standalone + // broadcast came through no route. + if reference.is_none() && (instance.is_none() || origin.is_none()) { return Ok(broadcast); - }; - - let origin = origin.ok_or_else(|| Error::UnresolvableBroadcast(reference.as_str().to_string()))?; + } + let origin = origin.ok_or_else(|| { + Error::UnresolvableBroadcast(reference.as_ref().map(|r| r.as_str().to_string()).unwrap_or_default()) + })?; let source = moq_mux::Source::new(origin.inner, broadcast); - // The C ABI does not expose a reference's instance yet, so it reads like an older reader: the - // first instance resolved, without the instance's guarantee. origin .driver - .watch(async { Ok(source.resolve(Some(&reference), None).await?) }) + .watch(async { Ok(source.resolve(reference.as_ref(), instance.as_ref()).await?) }) .await } @@ -643,6 +649,7 @@ impl Consume { // The rendition may live in a sibling broadcast, so resolve its reference rather than // assuming the catalog's own broadcast serves the track. let reference = config.broadcast().cloned(); + let instance = config.instance().cloned(); let broadcast = consume.broadcast.clone(); let origin = consume.origin.clone(); let driver = origin.as_ref().map(|origin| origin.driver.clone()).unwrap_or_default(); @@ -659,7 +666,7 @@ impl Consume { playout.subscription(moq_net::track::Subscription::default().with_priority(C::PRIORITY)); // Resolving a sibling broadcast can wait too, so the close races both steps. let setup = async { - let broadcast = resolve(broadcast, origin, reference).await?; + let broadcast = resolve(broadcast, origin, reference, instance).await?; Self::subscribe(&broadcast, &name, subscription).await }; let Some(track) = Self::until_closed(&mut close, setup).await? else { diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 98b4e4d7d3a..24c850a3a33 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -94,8 +94,9 @@ enum Family { Open { /// Handles that may still publish, ended on close. open: HashSet, - /// Finished producers, kept so a late subscriber still finds their tracks. - kept: Vec>, + /// Finished producers, kept so a late subscriber still finds their tracks, or `None` for + /// a family that drops them on finish. + kept: Option>>, }, /// The broadcast closed: its children ended and new ones are refused. Closed, @@ -123,7 +124,16 @@ impl Children { pub(crate) fn new() -> Self { Self(Arc::new(std::sync::Mutex::new(Family::Open { open: HashSet::new(), - kept: Vec::new(), + kept: Some(Vec::new()), + }))) + } + + /// A family that drops each finished producer instead of keeping it until the close, for + /// children no late subscriber looks up, such as a socket endpoint's streams. + pub(crate) fn unkept() -> Self { + Self(Arc::new(std::sync::Mutex::new(Family::Open { + open: HashSet::new(), + kept: None, }))) } @@ -153,12 +163,29 @@ impl Children { Err(Error::BroadcastNotFound) } - /// Keep `child`'s finished producer until the broadcast ends, or drop it now if it already has. + /// Keep `child`'s finished producer until the broadcast ends, or drop it now if it already + /// has or the family keeps none. pub(crate) fn keep(&self, child: Child, producer: impl Send + 'static) { let producer: Box = Box::new(producer); - if let Family::Open { open, kept, .. } = &mut *self.lock() { + let mut family = self.lock(); + if let Family::Open { open, kept } = &mut *family { open.remove(&child); - kept.push(producer); + if let Some(kept) = kept { + kept.push(producer); + return; + } + } + // Dropped outside the lock: the last producer's drop tears its track down. + drop(family); + drop(producer); + } + + /// How many children are open and how many finished producers are kept. + #[cfg(test)] + pub(crate) fn counts(&self) -> (usize, usize) { + match &*self.lock() { + Family::Open { open, kept } => (open.len(), kept.as_ref().map_or(0, Vec::len)), + Family::Closed => (0, 0), } } diff --git a/rs/moq-c/src/socket.rs b/rs/moq-c/src/socket.rs index 63ba2ecd8fd..5e00212ad09 100644 --- a/rs/moq-c/src/socket.rs +++ b/rs/moq-c/src/socket.rs @@ -110,6 +110,12 @@ async fn deliver( } impl Socket { + /// The open and kept counts of an endpoint's children. + #[cfg(test)] + pub(crate) fn endpoint_children(&self, id: Id) -> (usize, usize) { + self.endpoints.get(id).expect("endpoint").children.counts() + } + fn endpoint(&self, id: Id) -> Result<&EndpointEntry, Error> { let endpoint = self.endpoints.get(id).ok_or(Error::NotFound)?; endpoint.driver.check()?; @@ -121,7 +127,7 @@ impl Socket { self.endpoints.insert(EndpointEntry { inner: Arc::new(inner), driver: origin.driver.clone(), - children: Children::new(), + children: Children::unkept(), }) } @@ -181,14 +187,17 @@ impl Socket { let watch = driver.clone(); let run = async move { loop { - let next = match first.take() { - Some(res) => res, - // `biased` so a pending close always wins over a ready dial. - None => tokio::select! { - biased; - _ = &mut close => return Ok(()), - res = kio::wait(&poll) => res, - }, + // `biased` so a pending close always wins over a ready dial, the one the + // first poll buffered included. + let next = tokio::select! { + biased; + _ = &mut close => return Ok(()), + res = async { + match first.take() { + Some(res) => res, + None => kio::wait(&poll).await, + } + } => res, }; let incoming = match next { Ok(incoming) => incoming, diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index a3374943c10..b465eacd7f8 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -5318,15 +5318,12 @@ fn follow_local() { assert_eq!(moq_origin_close(origin), 0); } -/// A catalog rendition may name a sibling broadcast (`./source`), and the track then lives -/// there, not on the broadcast the catalog came from. Ignoring the reference subscribes on the -/// catalog's own broadcast: `NotFound`, or a same-named local track with mismatched metadata. -#[test] -fn consume_audio_follows_a_sibling_broadcast_reference() { - let origin = id(moq_origin_create()); - +/// Publish an Opus rendition on `a/source` (served under `source_instance`) and describe it +/// in `a/pub`'s catalog as a sibling reference naming `rendition_instance`, returning +/// (source, media, broadcast). +fn publish_sibling_audio(origin: u32, source_instance: &str, rendition_instance: Option<&str>) -> (u32, u32, u32) { // Only the sibling serves the track; the catalog broadcast just describes it. - let source = publish_broadcast(origin, b"a/source"); + let source = create_route(origin, b"a/source", Some(&route_options(0, source_instance, false))).1; let init = opus_head(); let media = id(publish_audio( source, @@ -5351,6 +5348,10 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { let broadcast = publish_broadcast(origin, b"a/pub"); let codec = "opus"; + let sibling = "./source"; + let (instance, instance_len) = rendition_instance.map_or((std::ptr::null(), 0), |instance| { + (instance.as_ptr() as *const c_char, instance.len()) + }); let config = moq_audio_config { name: name.as_ptr() as *const c_char, name_len: name.len(), @@ -5367,28 +5368,26 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { has_jitter: false, warmup_us: 0, has_warmup: false, - broadcast: std::ptr::null(), - broadcast_len: 0, - instance: std::ptr::null(), - instance_len: 0, + broadcast: sibling.as_ptr() as *const c_char, + broadcast_len: sibling.len(), + instance, + instance_len, track: std::ptr::null(), track_len: 0, }; assert_eq!(unsafe { moq_publish_audio_config(broadcast, &config) }, 0); + (source, media, broadcast) +} - // The C config struct has no broadcast field, so point the rendition at the sibling here. - { - let mut state = State::lock(); - let catalog = state.publish.target(Id::try_from(broadcast).unwrap()).unwrap().catalog; - catalog - .modify() - .unwrap() - .audio - .renditions - .get_mut(&name) - .unwrap() - .broadcast = Some(moq_net::path::Relative::new("./source").unwrap()); - } +/// A catalog rendition may name a sibling broadcast (`./source`), and the track then lives +/// there, not on the broadcast the catalog came from. Ignoring the reference subscribes on the +/// catalog's own broadcast: `NotFound`, or a same-named local track with mismatched metadata. +/// The rendition's instance, when it matches the sibling's, does not get in the way. +#[test] +fn consume_audio_follows_a_sibling_broadcast_reference() { + let origin = id(moq_origin_create()); + let instance = fresh_instance(); + let (source, media, broadcast) = publish_sibling_audio(origin, &instance, Some(&instance)); let consume = request_broadcast(origin, b"a/pub"); let catalog_cb = Callback::new(); @@ -5431,6 +5430,39 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { assert_eq!(moq_origin_close(origin), 0); } +/// A rendition naming an instance refuses a sibling proven to serve another stream, rather +/// than delivering that stream's frames. +#[test] +fn consume_audio_refuses_a_sibling_of_another_instance() { + let origin = id(moq_origin_create()); + let (wanted, served) = (fresh_instance(), fresh_instance()); + let (source, media, broadcast) = publish_sibling_audio(origin, &served, Some(&wanted)); + + let consume = request_broadcast(origin, b"a/pub"); + let catalog_cb = Callback::new(); + let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_id = id(catalog_cb.recv()); + + let frame_cb = Callback::new(); + let _track = id(unsafe { moq_consume_audio(catalog_id, 0, &TEN_SECONDS, Some(channel_callback), frame_cb.ptr) }); + let payload = b"another stream"; + assert_eq!( + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(1_000_000)) }, + 0 + ); + let code = frame_cb.recv(); + assert!(code < 0, "a sibling of another instance is refused, got {code}"); + + assert_eq!(moq_consume_catalog_free(catalog_id), 0); + assert_eq!(moq_consume_catalog_cancel(catalog_task), 0); + assert_eq!(catalog_cb.recv_terminal(), 0, "catalog close delivers terminal 0"); + assert_eq!(moq_consume_close(consume), 0); + assert_eq!(moq_publish_media_finish(media), 0); + assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(moq_publish_close(source), 0); + assert_eq!(moq_origin_close(origin), 0); +} + #[test] fn follow_close_cancels() { let origin = id(moq_origin_create()); diff --git a/rs/moq-c/src/test/parity.rs b/rs/moq-c/src/test/parity.rs index 9318184d026..a6f7142bcdb 100644 --- a/rs/moq-c/src/test/parity.rs +++ b/rs/moq-c/src/test/parity.rs @@ -177,6 +177,61 @@ fn socket_track_round_trip_and_endpoint_close() { assert_eq!(moq_origin_close(origin), 0); } +#[test] +fn socket_finished_tracks_are_not_kept_by_the_endpoint() { + let origin = id(moq_origin_create()); + let (a, b) = (endpoint(origin, "a"), endpoint(origin, "b")); + let accepts = Callback::new(); + let _accept = id(unsafe { moq_socket_accept_track(b, Some(channel_callback), accepts.ptr) }); + let peer = "b"; + for round in 0..3u8 { + let dialed = Callback::new(); + let _dial = id(unsafe { + moq_socket_dial_track( + a, + peer.as_ptr().cast(), + peer.len(), + std::ptr::null(), + Some(channel_callback), + dialed.ptr, + ) + }); + let incoming = id(accepts.recv()); + let accepted = Callback::new(); + let _accepting = + id(unsafe { moq_socket_incoming_accept(incoming, std::ptr::null(), Some(channel_callback), accepted.ptr) }); + let client = id(dialed.recv()); + assert_eq!(dialed.recv_terminal(), 0); + let server = id(accepted.recv()); + assert_eq!(accepted.recv_terminal(), 0); + + let track = id(moq_socket_stream_writer(client)); + let frames = Callback::new(); + let _reader = id(unsafe { moq_socket_stream_reader(server, Some(channel_callback), frames.ptr) }); + let group = id(moq_publish_track_group(track)); + assert_eq!( + unsafe { moq_publish_group_frame(group, &round, 1, std::ptr::null()) }, + 0 + ); + assert_eq!(moq_publish_group_finish(group), 0); + assert_eq!(moq_publish_track_finish(track), 0); + assert_eq!(next_frame(&frames), [round]); + assert_eq!(frames.recv_terminal(), 0, "a finished track ends its reader cleanly"); + assert_eq!(moq_socket_stream_free(client), 0); + assert_eq!(moq_socket_stream_free(server), 0); + assert_eq!( + State::lock().socket.endpoint_children(Id::try_from(a).unwrap()), + (0, 0), + "round {round}: the endpoint neither tracks nor keeps a finished track" + ); + } + + assert_eq!(moq_socket_close(a), 0); + assert_eq!(moq_socket_close(b), 0); + assert_eq!(accepts.recv_terminal(), 0); + assert_eq!(moq_origin_close(origin), 0); +} + #[test] fn socket_reject_and_cancel() { let origin = id(moq_origin_create()); @@ -308,6 +363,63 @@ fn track_largest_and_group_ready() { assert_eq!(moq_origin_close(origin), 0); } +/// Closing a broadcast ends its open tracks' groups and so their ready waits, but a track +/// that declared its end keeps taking groups below it, so its group's wait lasts until the +/// group itself ends. +#[test] +fn group_ready_across_a_broadcast_close() { + let origin = id(moq_origin_create()); + let broadcast = publish_broadcast(origin, b"ready-close"); + let open = publish_named_track(broadcast, b"open"); + let declared = publish_named_track(broadcast, b"declared"); + assert_eq!(moq_publish_track_finish_at(declared, 1), 0); + + let (open_group, declared_group) = ( + id(moq_publish_track_group(open)), + id(moq_publish_track_group_at(declared, 0)), + ); + let (open_ready, declared_ready) = (Callback::new(), Callback::new()); + for (group, ready) in [(open_group, &open_ready), (declared_group, &declared_ready)] { + assert_eq!( + unsafe { moq_publish_group_ready(group, 1, Some(channel_callback), ready.ptr) }, + 0 + ); + } + #[expect( + clippy::disallowed_methods, + reason = "the test thread has no runtime; it gives the C API's runtime time to park the waits" + )] + std::thread::sleep(Duration::from_millis(50)); + + assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!( + open_ready.rx.recv_timeout(Duration::from_secs(2)), + Ok(0), + "the close ends the group" + ); + let payload = b"late"; + assert!( + unsafe { moq_publish_group_frame(open_group, payload.as_ptr(), payload.len(), µs(0)) } < 0, + "the next write reports why" + ); + assert!( + declared_ready.rx.recv_timeout(Duration::from_millis(100)).is_err(), + "a declared-end track's group stays writable" + ); + assert_eq!( + unsafe { moq_publish_group_frame(declared_group, payload.as_ptr(), payload.len(), µs(0)) }, + 0 + ); + assert_eq!(moq_publish_group_finish(declared_group), 0); + assert_eq!(declared_ready.rx.recv_timeout(Duration::from_secs(2)), Ok(0)); + + assert!( + moq_publish_group_abort(open_group, 0) < 0, + "the close already ended the group; this only releases its handle" + ); + assert_eq!(moq_origin_close(origin), 0); +} + #[test] fn timebase_handles_are_owned_by_their_broadcast() { let origin = id(moq_origin_create()); @@ -417,10 +529,23 @@ fn session_tokens_and_grants() { assert_eq!(moq_grant_free(id(code)), 0); } + // A watcher still running when the session closes ends cleanly. + let ending = Callback::new(); + let _watcher = id(unsafe { moq_session_grants(client, Some(channel_callback), ending.ptr) }); + assert_eq!(moq_grant_free(id(ending.recv())), 0); + assert_eq!(moq_session_close(session), 0); session_cb.recv_terminal(); assert_eq!(moq_session_close(client), 0); client_cb.recv_terminal(); + loop { + let code = ending.recv(); + if code <= 0 { + assert_eq!(code, 0, "a closed session ends the watch cleanly"); + break; + } + assert_eq!(moq_grant_free(id(code)), 0); + } assert_eq!(moq_server_close(server), 0); assert_eq!(server_cb.recv_terminal(), 0); assert_eq!(moq_origin_close(served), 0); From d402e02bd2c1b03dcf131927acf1924afea828ca Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 16:49:20 -0800 Subject: [PATCH 13/16] fix(moq-c): decoded consumers resolve rendition references moq_decode_audio and moq_decode_video now resolve a rendition's broadcast reference and instance, as the encoded consumers do. The group-ready tests block instead of timing out, and check parking synchronously. Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/audio.rs | 3 ++ rs/moq-c/src/consume.rs | 27 ++++++++++-- rs/moq-c/src/test.rs | 84 +++++++++++++++++++++++++++++++++++++ rs/moq-c/src/test/parity.rs | 38 +++++++++++------ rs/moq-c/src/video.rs | 3 ++ 5 files changed, 140 insertions(+), 15 deletions(-) diff --git a/rs/moq-c/src/audio.rs b/rs/moq-c/src/audio.rs index fe4a79a06c1..e6d576c9820 100644 --- a/rs/moq-c/src/audio.rs +++ b/rs/moq-c/src/audio.rs @@ -266,6 +266,7 @@ impl Audio { ) -> Result { let crate::consume::Rendition { broadcast, + origin, config: catalog, name, driver, @@ -279,6 +280,8 @@ impl Audio { |close| async move { driver .watch(async move { + // The rendition may live in a sibling broadcast. + let broadcast = crate::consume::Rendition::resolve(broadcast, origin, &catalog).await?; let consumer = moq_audio::decode::Consumer::new(&broadcast, &catalog, name, config).await?; Self::run(on_frame, consumer, close).await }) diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index f113d59487f..954876739a5 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -71,6 +71,7 @@ impl ConsumeCatalog { fn rendition(&self, name: &str, config: &C) -> Rendition { Rendition { broadcast: self.broadcast.clone(), + origin: self.origin.clone(), config: config.clone(), name: name.to_string(), driver: self @@ -129,15 +130,35 @@ impl Media for hang::catalog::AudioConfig { } } -/// A catalog rendition to decode: the broadcast and track serving it, and the owner whose panic -/// ends the decode. +/// A catalog rendition to decode: the catalog's broadcast and the origin that resolves the +/// rendition's reference against it, the track serving it, and the owner whose panic ends the +/// decode. pub struct Rendition { pub broadcast: moq_net::broadcast::Consumer, + pub(crate) origin: Option, pub config: C, pub name: String, pub driver: crate::ffi::Background, } +impl Rendition { + /// The broadcast serving the rendition, honoring its reference and instance like + /// [`moq_consume_video`](crate::moq_consume_video) does. Awaited inside the decode task. + pub(crate) async fn resolve( + broadcast: moq_net::broadcast::Consumer, + origin: Option, + config: &C, + ) -> Result { + resolve( + broadcast, + origin, + config.broadcast().cloned(), + config.instance().cloned(), + ) + .await + } +} + /// A broadcast handed to C, plus the origin cursor that named it. /// /// The origin is what lets a catalog rendition reference a sibling broadcast: only an origin @@ -159,7 +180,7 @@ struct ConsumeBroadcast { /// over a wire that carries no instance cannot prove one, so there it is best effort. Awaited /// inside the track task, never under the state lock, so `origin` is cloned out rather than /// borrowed. -async fn resolve( +pub(crate) async fn resolve( broadcast: moq_net::broadcast::Consumer, origin: Option, reference: Option, diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index b465eacd7f8..1d3cb46fdf7 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -5463,6 +5463,90 @@ fn consume_audio_refuses_a_sibling_of_another_instance() { assert_eq!(moq_origin_close(origin), 0); } +/// A decoded consumer follows a rendition's sibling reference and instance too, decoding the +/// sibling's track rather than looking for it on the catalog's own broadcast. +#[test] +fn decode_audio_follows_a_sibling_broadcast_reference() { + let origin = id(moq_origin_create()); + let instance = fresh_instance(); + let source = create_route(origin, b"d/source", Some(&route_options(0, &instance, false))).1; + let input = moq_audio_encoder_input { + format: moq_audio_sample_format::MOQ_AUDIO_SAMPLE_FORMAT_F32 as u32, + sample_rate: 48_000, + channels: 1, + }; + let output = moq_audio_encoder_output { + codec: c"opus".as_ptr(), + codec_len: 4, + sample_rate: 0, + channels: 0, + bitrate: 0, + frame_duration_us: 0, + }; + let producer = id(unsafe { moq_encode_audio(source, c"audio".as_ptr(), 5, &input, &output, 0) }); + let pcm: Vec = (0..960).flat_map(|i| (i as f32 / 960.0).to_le_bytes()).collect(); + let frame = moq_audio_frame { + timestamp: micros(0), + data: pcm.as_ptr(), + data_size: pcm.len(), + }; + assert_eq!(unsafe { moq_encode_audio_frame(producer, &frame) }, 0); + assert_eq!(moq_encode_audio_finish(producer), 0); + + // Describe the sibling's rendition in `d/pub`'s catalog, pointing back at it. + let broadcast = publish_broadcast(origin, b"d/pub"); + { + let mut state = State::lock(); + let (name, mut config) = { + let catalog = state.publish.target(Id::try_from(source).unwrap()).unwrap().catalog; + let catalog = catalog.modify().unwrap(); + let (name, config) = catalog.audio.renditions.iter().next().expect("one rendition"); + (name.clone(), config.clone()) + }; + config.broadcast = Some(moq_net::path::Relative::new("./source").unwrap()); + config.instance = Some(instance.parse().unwrap()); + let catalog = state.publish.target(Id::try_from(broadcast).unwrap()).unwrap().catalog; + catalog.modify().unwrap().audio.renditions.insert(name, config); + } + + let consume = request_broadcast(origin, b"d/pub"); + let catalog_cb = Callback::new(); + let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_id = id(catalog_cb.recv()); + let decoded = moq_audio_decoder_output { + format: moq_audio_sample_format::MOQ_AUDIO_SAMPLE_FORMAT_F32 as u32, + sample_rate: 0, + channels: 0, + delay: moq_delay { + max_us: 30_000_000, + ..moq_delay::default() + }, + start: 0, + fixed: false, + }; + let read_cb = Callback::new(); + id(unsafe { moq_decode_audio(catalog_id, 0, &decoded, Some(channel_callback), read_cb.ptr) }); + let mut frames = 0; + loop { + let code = read_cb.recv(); + if code <= 0 { + assert_eq!(code, 0, "the sibling's finished track closes cleanly"); + break; + } + frames += 1; + assert_eq!(moq_decode_audio_read_free(id(code)), 0); + } + assert!(frames > 0, "the sibling's audio decodes"); + + assert_eq!(moq_consume_catalog_free(catalog_id), 0); + assert_eq!(moq_consume_catalog_cancel(catalog_task), 0); + assert_eq!(catalog_cb.recv_catalog_terminal(), 0); + assert_eq!(moq_consume_close(consume), 0); + assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(moq_publish_close(source), 0); + assert_eq!(moq_origin_close(origin), 0); +} + #[test] fn follow_close_cancels() { let origin = id(moq_origin_create()); diff --git a/rs/moq-c/src/test/parity.rs b/rs/moq-c/src/test/parity.rs index a6f7142bcdb..4b5ab811bf1 100644 --- a/rs/moq-c/src/test/parity.rs +++ b/rs/moq-c/src/test/parity.rs @@ -345,14 +345,15 @@ fn track_largest_and_group_ready() { 0 ); // Let the wait park first: finishing must still end it, though moq-net does not wake - // `poll_ready` on a finish. + // `poll_ready` on a finish. Best effort: a runtime slow to poll only skips the parked case, + // since a wait first polled after the finish resolves at once. #[expect( clippy::disallowed_methods, reason = "the test thread has no runtime; it gives the C API's runtime time to park the wait" )] std::thread::sleep(Duration::from_millis(50)); assert_eq!(moq_publish_group_finish(first), 0); - assert_eq!(ready.rx.recv_timeout(Duration::from_secs(2)), Ok(0)); + assert_eq!(ready.recv(), 0); assert!( unsafe { moq_publish_group_ready(first, 1, Some(ignore_callback), std::ptr::null_mut()) } < 0, "a finished group's handle is gone" @@ -363,6 +364,21 @@ fn track_largest_and_group_ready() { assert_eq!(moq_origin_close(origin), 0); } +/// Whether a ready wait on raw `group` would park now, polled synchronously. +fn group_pending(group: u32) -> bool { + let (group, _ended) = State::lock().publish.group(Id::try_from(group).unwrap()).unwrap(); + let group = group.lock(); + let frame = moq_net::frame::Info { + size: 1, + timestamp: None, + }; + group + .as_ref() + .expect("the group handle is live") + .poll_ready(&kio::Waiter::noop(), &frame) + .is_pending() +} + /// Closing a broadcast ends its open tracks' groups and so their ready waits, but a track /// that declared its end keeps taking groups below it, so its group's wait lasts until the /// group itself ends. @@ -385,6 +401,9 @@ fn group_ready_across_a_broadcast_close() { 0 ); } + // Unread, so both waits have something to wait for. + assert!(group_pending(open_group) && group_pending(declared_group)); + // Best effort, as above: a wait first polled after the close still resolves the same way. #[expect( clippy::disallowed_methods, reason = "the test thread has no runtime; it gives the C API's runtime time to park the waits" @@ -392,26 +411,21 @@ fn group_ready_across_a_broadcast_close() { std::thread::sleep(Duration::from_millis(50)); assert_eq!(moq_publish_close(broadcast), 0); - assert_eq!( - open_ready.rx.recv_timeout(Duration::from_secs(2)), - Ok(0), - "the close ends the group" - ); + assert_eq!(open_ready.recv(), 0, "the close ends the group"); let payload = b"late"; assert!( unsafe { moq_publish_group_frame(open_group, payload.as_ptr(), payload.len(), µs(0)) } < 0, "the next write reports why" ); - assert!( - declared_ready.rx.recv_timeout(Duration::from_millis(100)).is_err(), - "a declared-end track's group stays writable" - ); + // Nothing will resolve the declared group's wait yet: it is still open and unread. + assert!(group_pending(declared_group), "a declared-end track's group stays open"); + assert!(declared_ready.rx.try_recv().is_err()); assert_eq!( unsafe { moq_publish_group_frame(declared_group, payload.as_ptr(), payload.len(), µs(0)) }, 0 ); assert_eq!(moq_publish_group_finish(declared_group), 0); - assert_eq!(declared_ready.rx.recv_timeout(Duration::from_secs(2)), Ok(0)); + assert_eq!(declared_ready.recv(), 0); assert!( moq_publish_group_abort(open_group, 0) < 0, diff --git a/rs/moq-c/src/video.rs b/rs/moq-c/src/video.rs index 03dfbac493d..fe10c9eca7b 100644 --- a/rs/moq-c/src/video.rs +++ b/rs/moq-c/src/video.rs @@ -825,6 +825,7 @@ impl Video { ) -> Result { let crate::consume::Rendition { broadcast, + origin, config: catalog, name, driver, @@ -838,6 +839,8 @@ impl Video { |close| async move { driver .watch(async move { + // The rendition may live in a sibling broadcast. + let broadcast = crate::consume::Rendition::resolve(broadcast, origin, &catalog).await?; let consumer = moq_video::decode::Consumer::new(&broadcast, &catalog, name, options).await?; Self::run(on_frame, consumer, close, output).await }) From a2205c31a31c644ed441557e646f7058a6a6069d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 16:56:14 -0800 Subject: [PATCH 14/16] test(moq-c): poll group-ready waits by hand to prove they parked The wait behind moq_publish_group_ready is now its own future, so the tests poll it directly: each asserts the wait parked, then that finishing the group or closing the broadcast wakes it, with no real-time sleeps. Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/api.rs | 33 ++++++++----- rs/moq-c/src/test/parity.rs | 93 ++++++++++++++++++++----------------- 2 files changed, 72 insertions(+), 54 deletions(-) diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 7e14786fa1e..19d86243aad 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -3894,20 +3894,10 @@ pub unsafe extern "C" fn moq_publish_group_ready( ffi::enter(move || { let group = ffi::parse_id(group)?; let callback = unsafe { ffi::OnStatus::new(user_data, on_ready)? }; - let (group, mut ended) = State::lock().publish.group(group)?; - let frame = moq_net::frame::Info { size, timestamp: None }; + let wait = group_ready(group, size)?; tokio::spawn(async move { let res = ffi::run(async { - let ready = kio::wait(|waiter| match group.lock().as_ref() { - Some(group) => group.poll_ready(waiter, &frame), - // Finished or aborted: the next write reports why. - None => std::task::Poll::Ready(()), - }); - // The handle ending also resolves it: a finish does not wake `poll_ready`. - tokio::select! { - () = ready => {} - _ = ended.changed() => {} - } + wait.await; Ok(()) }) .await; @@ -3917,6 +3907,25 @@ pub unsafe extern "C" fn moq_publish_group_ready( }) } +/// The wait behind [moq_publish_group_ready]: resolves once raw `group` can take a frame of +/// `size` bytes, or its handle ends. +pub(crate) fn group_ready(group: crate::Id, size: u64) -> Result + Send + 'static, Error> { + let (group, mut ended) = State::lock().publish.group(group)?; + let frame = moq_net::frame::Info { size, timestamp: None }; + Ok(async move { + let ready = kio::wait(|waiter| match group.lock().as_ref() { + Some(group) => group.poll_ready(waiter, &frame), + // Finished or aborted: the next write reports why. + None => std::task::Poll::Ready(()), + }); + // The handle ending also resolves it: a finish does not wake `poll_ready`. + tokio::select! { + () = ready => {} + _ = ended.changed() => {} + } + }) +} + /// Abort a raw group with an application error code. #[unsafe(no_mangle)] pub extern "C" fn moq_publish_group_abort(group: u32, error_code: u16) -> i32 { diff --git a/rs/moq-c/src/test/parity.rs b/rs/moq-c/src/test/parity.rs index 4b5ab811bf1..3ad0e72f33b 100644 --- a/rs/moq-c/src/test/parity.rs +++ b/rs/moq-c/src/test/parity.rs @@ -1,5 +1,7 @@ //! The binding features moq-c gained to match moq-ffi for the cut. +use std::sync::Arc; + use super::*; /// Open the socket endpoint `name` under `room` on `origin`. @@ -338,21 +340,16 @@ fn track_largest_and_group_ready() { assert!(present); assert_eq!((group, frame), (3, 1)); - // Nobody reads the group, so the wait resolves once the group is finished. + // Nobody reads the group, so the wait resolves once the group is finished. A parked wait + // must still wake, though moq-net does not wake `poll_ready` on a finish. + let mut parked = ReadyWait::park(first); let ready = Callback::new(); assert_eq!( unsafe { moq_publish_group_ready(first, 1, Some(channel_callback), ready.ptr) }, 0 ); - // Let the wait park first: finishing must still end it, though moq-net does not wake - // `poll_ready` on a finish. Best effort: a runtime slow to poll only skips the parked case, - // since a wait first polled after the finish resolves at once. - #[expect( - clippy::disallowed_methods, - reason = "the test thread has no runtime; it gives the C API's runtime time to park the wait" - )] - std::thread::sleep(Duration::from_millis(50)); assert_eq!(moq_publish_group_finish(first), 0); + assert!(parked.woken() && parked.poll(), "finishing wakes the parked wait"); assert_eq!(ready.recv(), 0); assert!( unsafe { moq_publish_group_ready(first, 1, Some(ignore_callback), std::ptr::null_mut()) } < 0, @@ -364,19 +361,46 @@ fn track_largest_and_group_ready() { assert_eq!(moq_origin_close(origin), 0); } -/// Whether a ready wait on raw `group` would park now, polled synchronously. -fn group_pending(group: u32) -> bool { - let (group, _ended) = State::lock().publish.group(Id::try_from(group).unwrap()).unwrap(); - let group = group.lock(); - let frame = moq_net::frame::Info { - size: 1, - timestamp: None, - }; - group - .as_ref() - .expect("the group handle is live") - .poll_ready(&kio::Waiter::noop(), &frame) - .is_pending() +/// A [moq_publish_group_ready] wait, polled by hand so a test knows it parked. +struct ReadyWait { + wait: std::pin::Pin + Send>>, + woken: Arc, +} + +#[derive(Default)] +struct Woken(std::sync::atomic::AtomicBool); + +impl std::task::Wake for Woken { + fn wake(self: Arc) { + self.0.store(true, std::sync::atomic::Ordering::SeqCst); + } +} + +impl ReadyWait { + /// Start waiting on raw `group`, asserting the wait parked. + fn park(group: u32) -> Self { + let mut wait = Self { + wait: Box::pin(crate::api::group_ready(Id::try_from(group).unwrap(), 1).unwrap()), + woken: Arc::default(), + }; + assert!(!wait.poll(), "the wait parks"); + wait + } + + /// Whether something woke the parked wait since it last polled. + fn woken(&self) -> bool { + self.woken.0.load(std::sync::atomic::Ordering::SeqCst) + } + + /// Poll once, returning whether the wait resolved. + fn poll(&mut self) -> bool { + self.woken.0.store(false, std::sync::atomic::Ordering::SeqCst); + let waker = std::task::Waker::from(self.woken.clone()); + self.wait + .as_mut() + .poll(&mut std::task::Context::from_waker(&waker)) + .is_ready() + } } /// Closing a broadcast ends its open tracks' groups and so their ready waits, but a track @@ -394,38 +418,23 @@ fn group_ready_across_a_broadcast_close() { id(moq_publish_track_group(open)), id(moq_publish_track_group_at(declared, 0)), ); - let (open_ready, declared_ready) = (Callback::new(), Callback::new()); - for (group, ready) in [(open_group, &open_ready), (declared_group, &declared_ready)] { - assert_eq!( - unsafe { moq_publish_group_ready(group, 1, Some(channel_callback), ready.ptr) }, - 0 - ); - } - // Unread, so both waits have something to wait for. - assert!(group_pending(open_group) && group_pending(declared_group)); - // Best effort, as above: a wait first polled after the close still resolves the same way. - #[expect( - clippy::disallowed_methods, - reason = "the test thread has no runtime; it gives the C API's runtime time to park the waits" - )] - std::thread::sleep(Duration::from_millis(50)); + // Unread, so both waits park. + let (mut open_wait, mut declared_wait) = (ReadyWait::park(open_group), ReadyWait::park(declared_group)); assert_eq!(moq_publish_close(broadcast), 0); - assert_eq!(open_ready.recv(), 0, "the close ends the group"); + assert!(open_wait.woken() && open_wait.poll(), "the close ends the group"); let payload = b"late"; assert!( unsafe { moq_publish_group_frame(open_group, payload.as_ptr(), payload.len(), µs(0)) } < 0, "the next write reports why" ); - // Nothing will resolve the declared group's wait yet: it is still open and unread. - assert!(group_pending(declared_group), "a declared-end track's group stays open"); - assert!(declared_ready.rx.try_recv().is_err()); + assert!(!declared_wait.poll(), "a declared-end track's group stays open"); assert_eq!( unsafe { moq_publish_group_frame(declared_group, payload.as_ptr(), payload.len(), µs(0)) }, 0 ); assert_eq!(moq_publish_group_finish(declared_group), 0); - assert_eq!(declared_ready.recv(), 0); + assert!(declared_wait.woken() && declared_wait.poll()); assert!( moq_publish_group_abort(open_group, 0) < 0, From f9578c4eb37cbf365fd4b3b349b7a5c09313b7c3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 21:55:31 -0800 Subject: [PATCH 15/16] fix(moq-c): a decoder cancel ends its sibling resolve wait moq_decode_audio/video awaited Rendition::resolve and the decoder's SUBSCRIBE_OK before polling close, so a cancel while a sibling broadcast was unannounced parked the task forever. Race the setup against close through Consume::until_closed, as moq_consume_* already does. Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/audio.rs | 14 +++++++--- rs/moq-c/src/consume.rs | 2 +- rs/moq-c/src/test.rs | 60 +++++++++++++++++++++++++++++++++++++++++ rs/moq-c/src/video.rs | 14 +++++++--- 4 files changed, 81 insertions(+), 9 deletions(-) diff --git a/rs/moq-c/src/audio.rs b/rs/moq-c/src/audio.rs index e6d576c9820..3fb66bbee92 100644 --- a/rs/moq-c/src/audio.rs +++ b/rs/moq-c/src/audio.rs @@ -277,12 +277,18 @@ impl Audio { self.consumer_tasks.spawn( on_frame, |state| &mut state.audio.consumer_tasks, - |close| async move { + |mut close| async move { driver .watch(async move { - // The rendition may live in a sibling broadcast. - let broadcast = crate::consume::Rendition::resolve(broadcast, origin, &catalog).await?; - let consumer = moq_audio::decode::Consumer::new(&broadcast, &catalog, name, config).await?; + // The rendition may live in a sibling broadcast that is never announced, and + // SUBSCRIBE_OK may never come, so the close races both steps. + let setup = async { + let broadcast = crate::consume::Rendition::resolve(broadcast, origin, &catalog).await?; + Ok(moq_audio::decode::Consumer::new(&broadcast, &catalog, name, config).await?) + }; + let Some(consumer) = crate::consume::Consume::until_closed(&mut close, setup).await? else { + return Ok(()); + }; Self::run(on_frame, consumer, close).await }) .await diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index 954876739a5..9209f9193c2 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -778,7 +778,7 @@ impl Consume { /// /// A publisher can leave SUBSCRIBE_OK pending forever, so a cancel must not wait on it. /// `close` is left unpolled once it fires, since a oneshot panics if polled again. - async fn until_closed( + pub(crate) async fn until_closed( close: &mut oneshot::Receiver<()>, setup: impl Future>, ) -> Result, Error> { diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 1d3cb46fdf7..2bc2a26517e 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -5463,6 +5463,66 @@ fn consume_audio_refuses_a_sibling_of_another_instance() { assert_eq!(moq_origin_close(origin), 0); } +/// A decoder whose rendition names a sibling broadcast that is never announced waits on it +/// forever, so a cancel during that wait must still end the task with a terminal `0`. +#[test] +fn decoders_cancel_while_resolving_a_sibling() { + let origin = id(moq_origin_create()); + let broadcast = publish_broadcast(origin, b"r/pub"); + { + let mut state = State::lock(); + let catalog = state.publish.target(Id::try_from(broadcast).unwrap()).unwrap().catalog; + let mut catalog = catalog.modify().unwrap(); + let missing = moq_net::path::Relative::new("./missing").unwrap(); + let mut audio = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Opus, 48_000, 2); + audio.broadcast = Some(missing.clone()); + catalog.audio.renditions.insert("audio".to_string(), audio); + let mut video = hang::catalog::VideoConfig::new(hang::catalog::VideoCodec::VP8); + video.broadcast = Some(missing); + catalog.video.renditions.insert("video".to_string(), video); + } + + let consume = request_broadcast(origin, b"r/pub"); + let catalog_cb = Callback::new(); + let catalog_task = id(unsafe { moq_consume_catalog(consume, Some(channel_callback), catalog_cb.ptr) }); + let catalog_id = id(catalog_cb.recv()); + + let audio_output = moq_audio_decoder_output { + format: moq_audio_sample_format::MOQ_AUDIO_SAMPLE_FORMAT_F32 as u32, + sample_rate: 0, + channels: 0, + delay: moq_delay::default(), + start: 0, + fixed: false, + }; + let audio_cb = Callback::new(); + let audio = id(unsafe { moq_decode_audio(catalog_id, 0, &audio_output, Some(channel_callback), audio_cb.ptr) }); + let video_output = moq_video_decoder_output { + delay: moq_delay::default(), + format: moq_video_pixel_format::MOQ_VIDEO_PIXEL_FORMAT_I420 as u32, + width: 0, + height: 0, + start: 0, + surface: false, + }; + let video_cb = Callback::new(); + let video = id(unsafe { moq_decode_video(catalog_id, 0, &video_output, Some(channel_callback), video_cb.ptr) }); + + assert_eq!(moq_decode_audio_cancel(audio), 0); + let code = audio_cb.rx.recv_timeout(TIMEOUT).expect("audio cancel ends the resolve wait"); + assert_eq!(code, 0, "a cancelled audio decoder ends cleanly"); + assert_eq!(moq_decode_video_cancel(video), 0); + let code = video_cb.rx.recv_timeout(TIMEOUT).expect("video cancel ends the resolve wait"); + assert_eq!(code, 0, "a cancelled video decoder ends cleanly"); + + assert_eq!(moq_consume_catalog_free(catalog_id), 0); + assert_eq!(moq_consume_catalog_cancel(catalog_task), 0); + assert_eq!(catalog_cb.recv_terminal(), 0); + assert_eq!(moq_consume_close(consume), 0); + assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(moq_origin_close(origin), 0); +} + /// A decoded consumer follows a rendition's sibling reference and instance too, decoding the /// sibling's track rather than looking for it on the catalog's own broadcast. #[test] diff --git a/rs/moq-c/src/video.rs b/rs/moq-c/src/video.rs index fe10c9eca7b..6b44b18a3d1 100644 --- a/rs/moq-c/src/video.rs +++ b/rs/moq-c/src/video.rs @@ -836,12 +836,18 @@ impl Video { self.consumer_tasks.spawn( on_frame, |state| &mut state.video.consumer_tasks, - |close| async move { + |mut close| async move { driver .watch(async move { - // The rendition may live in a sibling broadcast. - let broadcast = crate::consume::Rendition::resolve(broadcast, origin, &catalog).await?; - let consumer = moq_video::decode::Consumer::new(&broadcast, &catalog, name, options).await?; + // The rendition may live in a sibling broadcast that is never announced, and + // SUBSCRIBE_OK may never come, so the close races both steps. + let setup = async { + let broadcast = crate::consume::Rendition::resolve(broadcast, origin, &catalog).await?; + Ok(moq_video::decode::Consumer::new(&broadcast, &catalog, name, options).await?) + }; + let Some(consumer) = crate::consume::Consume::until_closed(&mut close, setup).await? else { + return Ok(()); + }; Self::run(on_frame, consumer, close, output).await }) .await From ec6cb0d6016699b1910d0bf82910b55f30fa256f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 7 Nov 2026 22:00:09 -0800 Subject: [PATCH 16/16] style(moq-c): format the resolve-cancel test Co-Authored-By: Claude Opus 5.5 --- rs/moq-c/src/test.rs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 2bc2a26517e..13304162ecb 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -5509,10 +5509,16 @@ fn decoders_cancel_while_resolving_a_sibling() { let video = id(unsafe { moq_decode_video(catalog_id, 0, &video_output, Some(channel_callback), video_cb.ptr) }); assert_eq!(moq_decode_audio_cancel(audio), 0); - let code = audio_cb.rx.recv_timeout(TIMEOUT).expect("audio cancel ends the resolve wait"); + let code = audio_cb + .rx + .recv_timeout(TIMEOUT) + .expect("audio cancel ends the resolve wait"); assert_eq!(code, 0, "a cancelled audio decoder ends cleanly"); assert_eq!(moq_decode_video_cancel(video), 0); - let code = video_cb.rx.recv_timeout(TIMEOUT).expect("video cancel ends the resolve wait"); + let code = video_cb + .rx + .recv_timeout(TIMEOUT) + .expect("video cancel ends the resolve wait"); assert_eq!(code, 0, "a cancelled video decoder ends cleanly"); assert_eq!(moq_consume_catalog_free(catalog_id), 0);