reactor-effect-native 0.2.0 → 0.3.0-rc.0

package/rust/src/peer/owner.rs

@@ -0,0 +1,353 @@
+//! The owner thread: the one thread that holds a peer's libwebrtc objects.
+
+use super::{Shared, callbacks};
+use crate::abi::{Channel, MAX_BUFFERED_SEND_BYTES, Operation};
+use crate::error::{BridgeError, Classify, FailureClass};
+use crate::protocol::{
+    self, BitrateRequest, Direction, DirectionRequest, Mapping, PrepareRequest, PrepareResponse,
+    stats_json,
+};
+use crate::sync::lock;
+use reactor_webrtc::{
+    DataChannel, DataChannelState, PeerConnection, PeerConnectionFactory, RtcConfiguration,
+    SdpType, SessionDescription, Transceiver, TransceiverDirection,
+};
+use std::collections::HashMap;
+use std::sync::mpsc::{Receiver, SyncSender};
+use std::sync::{Arc, Mutex};
+
+#[cfg(test)]
+mod tests;
+
+/// Where the owner thread sends one command's result.
+pub(crate) type Reply<T> = SyncSender<Result<T, BridgeError>>;
+
+/// Work for the owner thread, which runs commands one at a time.
+pub(crate) enum Command {
+    Call {
+        operation: Operation,
+        request: Vec<u8>,
+        reply: Reply<Vec<u8>>,
+    },
+    Send {
+        channel: Channel,
+        bytes: Vec<u8>,
+        reply: Reply<()>,
+    },
+    Shutdown,
+}
+
+/// libwebrtc's threads are process-global, so reactor-webrtc requires one
+/// factory per process. Every peer shares this one; it is created on first
+/// use and never destroyed. A `Mutex` rather than a `OnceLock` lets a failed
+/// creation be retried.
+static FACTORY: Mutex<Option<&'static PeerConnectionFactory>> = Mutex::new(None);
+
+/// The process's libwebrtc factory.
+pub(crate) fn factory() -> Result<&'static PeerConnectionFactory, BridgeError> {
+    let mut slot = lock(&FACTORY);
+    if let Some(factory) = *slot {
+        return Ok(factory);
+    }
+    let factory = PeerConnectionFactory::builder()
+        .with_synthetic_adm()
+        .build()
+        .classify(FailureClass::Native, "create_factory")?;
+    let factory: &'static PeerConnectionFactory = Box::leak(Box::new(factory));
+    *slot = Some(factory);
+    Ok(factory)
+}
+
+/// Send a command's result to the peer that queued it.
+fn respond<T>(reply: &Reply<T>, result: Result<T, BridgeError>) {
+    #[expect(
+        clippy::let_underscore_must_use,
+        reason = "the peer waits for every reply, so a failed send means a panic unwound it \
+                  and no one is waiting"
+    )]
+    let _ = reply.send(result);
+}
+
+/// A negotiated connection and the libwebrtc objects created with it.
+struct Connection {
+    peer: PeerConnection,
+    control: DataChannel,
+    data: DataChannel,
+    tracks: HashMap<String, Track>,
+}
+
+impl Connection {
+    fn channel(&self, channel: Channel) -> &DataChannel {
+        match channel {
+            Channel::Control => &self.control,
+            Channel::Data => &self.data,
+        }
+    }
+}
+
+/// A declared track's transceiver.
+struct Track {
+    direction: Direction,
+    transceiver: Transceiver,
+}
+
+/// The owner thread's state.
+pub(crate) struct Owner {
+    shared: Arc<Shared>,
+    /// Set by `Prepare`.
+    connection: Option<Connection>,
+}
+
+impl Owner {
+    pub(crate) fn new(shared: Arc<Shared>) -> Self {
+        Self {
+            shared,
+            connection: None,
+        }
+    }
+
+    /// Run commands until shutdown, then release the libwebrtc objects and
+    /// wait for every admitted callback to return.
+    pub(crate) fn run(mut self, commands: &Receiver<Command>) {
+        while let Ok(command) = commands.recv() {
+            match command {
+                Command::Call {
+                    operation,
+                    request,
+                    reply,
+                } => {
+                    let result = self.unless_closed(|owner| owner.call(operation, &request));
+                    respond(&reply, result);
+                }
+                Command::Send {
+                    channel,
+                    bytes,
+                    reply,
+                } => {
+                    let result = self.unless_closed(|owner| owner.send(channel, &bytes));
+                    respond(&reply, result);
+                }
+                Command::Shutdown => break,
+            }
+        }
+        self.shutdown();
+    }
+
+    /// Run a command, unless the peer closed while it waited in the queue.
+    fn unless_closed<T>(
+        &mut self,
+        command: impl FnOnce(&mut Self) -> Result<T, BridgeError>,
+    ) -> Result<T, BridgeError> {
+        if self.shared.gate.is_open() {
+            command(self)
+        } else {
+            Err(BridgeError::closed())
+        }
+    }
+
+    fn call(&mut self, operation: Operation, request: &[u8]) -> Result<Vec<u8>, BridgeError> {
+        match operation {
+            Operation::Prepare => self.prepare(request),
+            Operation::Answer => self.answer(request),
+            Operation::Direction => self.set_direction(request),
+            Operation::MaxBitrate => self.set_max_bitrate(request),
+            Operation::Stats => self.stats(),
+            // The peer answers snapshots itself so they never wait behind a
+            // blocking call; answering one here as well keeps this total.
+            Operation::MediaSnapshot => protocol::encode(&self.shared.snapshot()),
+        }
+    }
+
+    /// Create the connection, its data channels and a transceiver per
+    /// declared track, and return the local offer with each track's MID.
+    fn prepare(&mut self, request: &[u8]) -> Result<Vec<u8>, BridgeError> {
+        if self.connection.is_some() {
+            return Err(BridgeError::invalid("native peer is already prepared"));
+        }
+        let request = PrepareRequest::parse(request)?;
+        let config = RtcConfiguration {
+            ice_servers: request.servers.iter().map(Into::into).collect(),
+            ..RtcConfiguration::default()
+        };
+        let peer = factory()?
+            .create_peer_connection(&config, callbacks::observer(&self.shared))
+            .classify(FailureClass::Native, "create_peer_connection")?;
+        let control = callbacks::open_channel(&peer, Channel::Control, &self.shared)?;
+        let data = callbacks::open_channel(&peer, Channel::Data, &self.shared)?;
+        let transceivers = request
+            .tracks
+            .iter()
+            .map(|track| {
+                peer.add_transceiver(track.kind.into(), track.direction.into())
+                    .classify(FailureClass::Native, "add_transceiver")
+            })
+            .collect::<Result<Vec<_>, _>>()?;
+
+        let offer = peer
+            .create_offer()
+            .classify(FailureClass::SdpRejected, "create_offer")?;
+        peer.set_local_description(&offer)
+            .classify(FailureClass::SdpRejected, "set_local_description")?;
+
+        // Transceivers have their MIDs once the local description is set.
+        let mapping = request
+            .tracks
+            .iter()
+            .zip(&transceivers)
+            .map(|(track, transceiver)| {
+                let mid = transceiver.mid().ok_or_else(|| {
+                    BridgeError::new(
+                        FailureClass::Native,
+                        format!("missing MID after local description: {}", track.name),
+                    )
+                })?;
+                Ok(Mapping {
+                    name: track.name.clone(),
+                    kind: track.kind,
+                    direction: track.direction,
+                    mid,
+                })
+            })
+            .collect::<Result<Vec<_>, BridgeError>>()?;
+        let response = protocol::encode(&PrepareResponse {
+            sdp: &offer.sdp,
+            mapping: &mapping,
+        })?;
+        self.shared.set_bindings(&mapping);
+
+        let tracks = request
+            .tracks
+            .into_iter()
+            .zip(transceivers)
+            .map(|(track, transceiver)| {
+                let track_state = Track {
+                    direction: track.direction,
+                    transceiver,
+                };
+                (track.name, track_state)
+            })
+            .collect();
+        self.connection = Some(Connection {
+            peer,
+            control,
+            data,
+            tracks,
+        });
+        Ok(response)
+    }
+
+    /// Apply the remote answer, which carries the remote peer's candidates.
+    fn answer(&self, request: &[u8]) -> Result<Vec<u8>, BridgeError> {
+        let sdp = std::str::from_utf8(request)
+            .map_err(|error| BridgeError::invalid(format!("answer SDP is not UTF-8: {error}")))?;
+        if sdp.is_empty() {
+            return Err(BridgeError::invalid("answer SDP is empty"));
+        }
+        let answer = SessionDescription {
+            kind: SdpType::Answer,
+            sdp: sdp.to_owned(),
+        };
+        self.connection()?
+            .peer
+            .set_remote_description(&answer)
+            .classify(FailureClass::SdpRejected, "set_remote_description")?;
+        Ok(protocol::empty_response())
+    }
+
+    /// Pause a declared track, or resume it in its declared direction.
+    fn set_direction(&self, request: &[u8]) -> Result<Vec<u8>, BridgeError> {
+        let request: DirectionRequest = protocol::decode(request)?;
+        let track = self.track(&request.name)?;
+        let direction = if request.active {
+            track.direction.into()
+        } else {
+            TransceiverDirection::Inactive
+        };
+        track
+            .transceiver
+            .set_direction(direction)
+            .classify(FailureClass::Native, "set_direction")?;
+        Ok(protocol::empty_response())
+    }
+
+    /// Cap an outgoing track's send bitrate.
+    fn set_max_bitrate(&self, request: &[u8]) -> Result<Vec<u8>, BridgeError> {
+        let request = BitrateRequest::parse(request)?;
+        let track = self.track(&request.name)?;
+        if track.direction != Direction::SendOnly {
+            return Err(BridgeError::invalid(format!(
+                "{} is not an outgoing track",
+                request.name
+            )));
+        }
+        track
+            .transceiver
+            .set_send_bitrate(None, Some(request.bits_per_second))
+            .classify(FailureClass::Native, "set_send_bitrate")?;
+        Ok(protocol::empty_response())
+    }
+
+    fn stats(&self) -> Result<Vec<u8>, BridgeError> {
+        let report = self
+            .connection()?
+            .peer
+            .get_stats()
+            .classify(FailureClass::Native, "get_stats")?;
+        protocol::encode(&stats_json(&report))
+    }
+
+    /// Send one binary message on an open bridge channel, unless it would
+    /// push the channel's unsent bytes past their bound.
+    fn send(&self, channel: Channel, bytes: &[u8]) -> Result<(), BridgeError> {
+        let open = self
+            .connection
+            .as_ref()
+            .map(|connection| connection.channel(channel))
+            .filter(|data_channel| data_channel.state() == DataChannelState::Open);
+        let Some(data_channel) = open else {
+            return Err(BridgeError::new(
+                FailureClass::ChannelClosed,
+                format!("{} channel is not open", channel.label()),
+            ));
+        };
+        let buffered = data_channel.buffered_amount();
+        if buffered.saturating_add(bytes.len() as u64) > MAX_BUFFERED_SEND_BYTES {
+            return Err(BridgeError::overflow(
+                "native data channel buffered amount bound exceeded",
+            ));
+        }
+        data_channel
+            .send(bytes, true)
+            .classify(FailureClass::Native, "send")
+    }
+
+    fn connection(&self) -> Result<&Connection, BridgeError> {
+        self.connection.as_ref().ok_or_else(BridgeError::closed)
+    }
+
+    fn track(&self, name: &str) -> Result<&Track, BridgeError> {
+        self.connection
+            .as_ref()
+            .and_then(|connection| connection.tracks.get(name))
+            .ok_or_else(|| BridgeError::invalid(format!("unknown track: {name}")))
+    }
+
+    /// Release the libwebrtc objects children first, wait for every admitted
+    /// callback to return, then close the queues.
+    fn shutdown(self) {
+        if let Some(Connection {
+            peer,
+            control,
+            data,
+            tracks,
+        }) = self.connection
+        {
+            drop((control, data));
+            self.shared.release_remote_tracks();
+            drop(tracks);
+            drop(peer);
+        }
+        self.shared.gate.wait_idle();
+        self.shared.close_queues();
+    }
+}

package/rust/src/peer/shared.rs

@@ -0,0 +1,323 @@
+//! The state a peer shares between its owner thread, libwebrtc callbacks and
+//! the host's takes.
+
+use super::media::{self, AudioItem, VideoItem};
+use crate::abi::Ready;
+use crate::error::FailureClass;
+use crate::protocol::{DecimalU64, Direction, Event, Mapping, MediaSnapshot, TrackKind};
+use crate::sync::{CallbackGate, Notifier, Push, Queue, lock};
+use reactor_webrtc::RemoteTrack;
+use std::collections::VecDeque;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+
+// Queue bounds. No single item can exceed its queue's byte bound, so the host
+// sizes its take buffers from them: keep them in step with the MAX_*_BYTES and
+// MAX_AUDIO_SAMPLES constants in packages/native/src/_internal/bridge.ts.
+const EVENT_QUEUE_ITEMS: usize = 1024;
+const EVENT_QUEUE_BYTES: usize = 16 * 1024 * 1024;
+/// A third of a second at 24 fps.
+const VIDEO_QUEUE_FRAMES: usize = 8;
+const VIDEO_QUEUE_BYTES: usize = 64 * 1024 * 1024;
+/// 2.56 s of 10 ms blocks.
+const AUDIO_QUEUE_BLOCKS: usize = 256;
+const AUDIO_QUEUE_BYTES: usize = 4 * 1024 * 1024;
+// A media item's C header states its lengths as `u32`.
+const _: () = assert!(VIDEO_QUEUE_BYTES <= u32::MAX as usize);
+const _: () = assert!(AUDIO_QUEUE_BYTES <= u32::MAX as usize);
+
+/// What a peer's threads share. libwebrtc callbacks copy into its queues and
+/// signal readiness; the host takes from the queues.
+pub(crate) struct Shared {
+    /// Admits libwebrtc callbacks, and host calls, until the peer closes.
+    pub(crate) gate: CallbackGate,
+    /// Transport events, each an encoded packet.
+    pub(crate) events: Queue<Vec<u8>>,
+    pub(crate) video: Queue<VideoItem>,
+    pub(crate) audio: Queue<AudioItem>,
+    pub(crate) notifier: Notifier,
+    /// Declared receive tracks not yet claimed by a remote track.
+    bindings: Mutex<Bindings>,
+    /// Remote tracks, kept alive so their sinks keep delivering.
+    remote_tracks: Mutex<Vec<RemoteTrack>>,
+    /// Set once an event is lost, which retires the connection.
+    retired: AtomicBool,
+}
+
+/// A declared receive track waiting for its remote track.
+#[derive(Debug)]
+struct Binding {
+    name: String,
+    mid: String,
+    /// The track's index in the prepare request.
+    index: u32,
+}
+
+/// Unclaimed bindings per kind, in declaration order.
+///
+/// Pinned reactor-webrtc does not tell a remote track's MID, so a remote
+/// track claims the first unclaimed binding of its kind. The host therefore
+/// declares at most one receive track per kind.
+#[derive(Debug, Default)]
+struct Bindings {
+    video: VecDeque<Binding>,
+    audio: VecDeque<Binding>,
+}
+
+impl Shared {
+    pub(crate) fn new() -> Self {
+        Self {
+            gate: CallbackGate::new(),
+            events: Queue::new(EVENT_QUEUE_ITEMS, EVENT_QUEUE_BYTES),
+            video: Queue::new(VIDEO_QUEUE_FRAMES, VIDEO_QUEUE_BYTES),
+            audio: Queue::new(AUDIO_QUEUE_BLOCKS, AUDIO_QUEUE_BYTES),
+            notifier: Notifier::default(),
+            bindings: Mutex::default(),
+            remote_tracks: Mutex::default(),
+            retired: AtomicBool::new(false),
+        }
+    }
+
+    /// Run a libwebrtc callback's body unless the peer has closed. Shutdown
+    /// waits for the body to return.
+    pub(crate) fn admit(&self, body: impl FnOnce()) {
+        if let Some(_running) = self.gate.enter() {
+            body();
+        }
+    }
+
+    /// Queue a transport event for the host. An event that cannot be queued
+    /// retires the connection rather than go missing.
+    pub(crate) fn emit(&self, event: &Event<'_>) {
+        let packet = match event.to_packet() {
+            Ok(packet) => packet,
+            Err(error) => {
+                self.retire(error.class, &error.message);
+                return;
+            }
+        };
+        match self.events.try_push(packet) {
+            Push::Accepted => self.notifier.signal(Ready::Events),
+            Push::Closed => {}
+            Push::Overflow => self.retire(
+                FailureClass::Overflow,
+                "native transport event queue overflowed; connection retired",
+            ),
+        }
+    }
+
+    /// Report a failure of the connection itself as an `error` event.
+    pub(crate) fn emit_error(&self, class: FailureClass, message: &str) {
+        self.emit(&Event::error(class, message));
+    }
+
+    /// Retire the connection: fence admission and replace the event backlog
+    /// with the one diagnostic that says why.
+    fn retire(&self, class: FailureClass, message: &str) {
+        if self.retired.swap(true, Ordering::AcqRel) {
+            return;
+        }
+        self.gate.close();
+        if let Ok(diagnostic) = Event::error(class, message).to_packet() {
+            self.events.replace(diagnostic);
+            self.notifier.signal(Ready::Events);
+        } else {
+            // Without its diagnostic, closed queues still tell the host that
+            // the connection is gone.
+            self.close_queues();
+        }
+    }
+
+    pub(crate) fn push_video(&self, frame: VideoItem) {
+        if self.video.push_drop_oldest(frame) {
+            self.notifier.signal(Ready::Video);
+        }
+    }
+
+    pub(crate) fn push_audio(&self, block: AudioItem) {
+        if self.audio.push_drop_oldest(block) {
+            self.notifier.signal(Ready::Audio);
+        }
+    }
+
+    /// Record which declared tracks remote tracks may claim.
+    pub(crate) fn set_bindings(&self, mapping: &[Mapping]) {
+        let mut bindings = Bindings::default();
+        for (index, entry) in (0..).zip(mapping) {
+            if entry.direction != Direction::RecvOnly {
+                continue;
+            }
+            let binding = Binding {
+                name: entry.name.clone(),
+                mid: entry.mid.clone(),
+                index,
+            };
+            match entry.kind {
+                TrackKind::Video => bindings.video.push_back(binding),
+                TrackKind::Audio => bindings.audio.push_back(binding),
+            }
+        }
+        *lock(&self.bindings) = bindings;
+    }
+
+    fn claim_binding(&self, kind: TrackKind) -> Option<Binding> {
+        let mut bindings = lock(&self.bindings);
+        match kind {
+            TrackKind::Video => bindings.video.pop_front(),
+            TrackKind::Audio => bindings.audio.pop_front(),
+        }
+    }
+
+    /// Bind a remote track to a declared receive track and route its decoded
+    /// media to the queues. A track nobody declared breaks the negotiated
+    /// contract.
+    pub(crate) fn accept_remote(self: &Arc<Self>, track: RemoteTrack) {
+        let kind = media::kind_of(&track);
+        let Some(binding) = self.claim_binding(kind) else {
+            self.emit_error(
+                FailureClass::Protocol,
+                "received native track without a declared receive mapping",
+            );
+            return;
+        };
+        media::route(&track, binding.index, self);
+        let (name, mid) = (binding.name.as_str(), binding.mid.as_str());
+        self.emit(&Event::Track { name, mid });
+        self.emit(&Event::Decoded { kind, name, mid });
+        lock(&self.remote_tracks).push(track);
+    }
+
+    /// Drop the remote tracks, which stops their sinks.
+    pub(crate) fn release_remote_tracks(&self) {
+        lock(&self.remote_tracks).clear();
+    }
+
+    pub(crate) fn snapshot(&self) -> MediaSnapshot {
+        let (events, video, audio) = (
+            self.events.counts(),
+            self.video.counts(),
+            self.audio.counts(),
+        );
+        MediaSnapshot {
+            closed: !self.gate.is_open(),
+            queued_control: events.queued,
+            queued_video: video.queued,
+            queued_audio: audio.queued,
+            queued_bytes: events.bytes + video.bytes + audio.bytes,
+            dropped_video: DecimalU64(video.dropped),
+            dropped_audio: DecimalU64(audio.dropped),
+            delivered_video: DecimalU64(video.taken),
+            delivered_audio: DecimalU64(audio.taken),
+            pending_requests: 0,
+        }
+    }
+
+    /// Fence admission and discard what is queued: `reactor_effect_peer_close`.
+    pub(crate) fn close(&self) {
+        self.gate.close();
+        self.close_queues();
+    }
+
+    /// Refuse later items, discard queued ones and stop the notifier thread.
+    pub(crate) fn close_queues(&self) {
+        self.events.close();
+        self.video.close();
+        self.audio.close();
+        self.notifier.close();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::abi::Status;
+    use crate::sync::Taken;
+    use crate::test_support::parse_packet;
+    use serde_json::json;
+
+    fn mapping(name: &str, kind: TrackKind, direction: Direction) -> Mapping {
+        Mapping {
+            name: name.into(),
+            kind,
+            direction,
+            mid: format!("mid-{name}"),
+        }
+    }
+
+    #[test]
+    fn event_overflow_retires_the_connection_with_one_diagnostic() {
+        let shared = Shared::new();
+        for index in 0..EVENT_QUEUE_ITEMS {
+            let name = index.to_string();
+            shared.emit(&Event::Track {
+                name: &name,
+                mid: "0",
+            });
+        }
+        assert!(shared.gate.is_open());
+
+        shared.emit(&Event::Ice { candidate: None });
+        assert!(
+            !shared.gate.is_open(),
+            "overflow must retire the connection"
+        );
+        assert_eq!(shared.events.counts().queued, 1, "the backlog collapses");
+        let Taken::Item(packet) = shared.events.take(|_| true) else {
+            panic!("the overflow diagnostic must be queued");
+        };
+        let (header, payload) = parse_packet(&packet);
+        assert!(payload.is_empty());
+        assert_eq!(header["type"], "error");
+        assert_eq!(header["status"], Status::Overflow.code());
+    }
+
+    #[test]
+    fn remote_tracks_claim_declared_receive_tracks_by_kind_in_order() {
+        let shared = Shared::new();
+        shared.set_bindings(&[
+            mapping("out", TrackKind::Video, Direction::SendOnly),
+            mapping("video", TrackKind::Video, Direction::RecvOnly),
+            mapping("audio", TrackKind::Audio, Direction::RecvOnly),
+            mapping("second", TrackKind::Video, Direction::RecvOnly),
+        ]);
+        let claimed = |kind| {
+            shared
+                .claim_binding(kind)
+                .map(|binding| (binding.name, binding.index))
+        };
+        assert_eq!(claimed(TrackKind::Audio), Some(("audio".into(), 2)));
+        assert_eq!(claimed(TrackKind::Video), Some(("video".into(), 1)));
+        assert_eq!(claimed(TrackKind::Video), Some(("second".into(), 3)));
+        assert_eq!(
+            claimed(TrackKind::Video),
+            None,
+            "sending tracks are never claimed"
+        );
+        assert_eq!(claimed(TrackKind::Audio), None);
+    }
+
+    #[test]
+    fn close_fences_events_and_media_and_the_snapshot_says_so() {
+        let shared = Shared::new();
+        shared.emit(&Event::Ice { candidate: None });
+        shared.close();
+        shared.emit(&Event::Ice { candidate: None });
+        assert_eq!(shared.events.take(|_| true), Taken::Closed);
+        let snapshot = serde_json::to_value(shared.snapshot()).unwrap();
+        assert_eq!(
+            snapshot,
+            json!({
+                "closed": true,
+                "queuedControl": 0,
+                "queuedVideo": 0,
+                "queuedAudio": 0,
+                "queuedBytes": 0,
+                "droppedVideo": "0",
+                "droppedAudio": "0",
+                "deliveredVideo": "0",
+                "deliveredAudio": "0",
+                "pendingRequests": 0,
+            })
+        );
+    }
+}