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

package/rust/src/peer/callbacks.rs

@@ -0,0 +1,145 @@
+//! libwebrtc callbacks. Each runs on a libwebrtc thread, is admitted through
+//! the peer's callback gate, and only copies into the shared queues: none
+//! calls or waits on the host.
+
+use super::Shared;
+use crate::abi::{Channel, MAX_MESSAGE_BYTES};
+use crate::error::{BridgeError, Classify, FailureClass};
+use crate::protocol::{Event, LocalCandidate, connection_state};
+use reactor_webrtc::{
+    DataChannel, DataChannelState, IceGatheringState, PeerConnection, PeerConnectionObserver,
+};
+use std::sync::Arc;
+
+/// The connection's observer: state changes, local ICE candidates and remote
+/// tracks become events.
+pub(crate) fn observer(shared: &Arc<Shared>) -> PeerConnectionObserver {
+    PeerConnectionObserver::new()
+        .on_connection_state_change({
+            let shared = Arc::clone(shared);
+            move |state| {
+                shared.admit(|| {
+                    shared.emit(&Event::State {
+                        state: connection_state(state),
+                    });
+                });
+            }
+        })
+        .on_ice_gathering_change({
+            let shared = Arc::clone(shared);
+            move |state| {
+                shared.admit(|| {
+                    if state == IceGatheringState::Complete {
+                        shared.emit(&Event::Ice { candidate: None });
+                    }
+                });
+            }
+        })
+        .on_ice_candidate({
+            let shared = Arc::clone(shared);
+            move |candidate| {
+                shared.admit(|| {
+                    shared.emit(&Event::Ice {
+                        candidate: Some(LocalCandidate::from(&candidate)),
+                    });
+                });
+            }
+        })
+        .on_track({
+            let shared = Arc::clone(shared);
+            move |track| shared.admit(|| shared.accept_remote(track))
+        })
+}
+
+/// Create one of the bridge's data channels and turn its messages and state
+/// changes into events.
+pub(crate) fn open_channel(
+    peer: &PeerConnection,
+    channel: Channel,
+    shared: &Arc<Shared>,
+) -> Result<DataChannel, BridgeError> {
+    let mut data_channel = peer
+        .create_data_channel(channel.label())
+        .classify(FailureClass::Native, "create_data_channel")?;
+    data_channel.on_message({
+        let shared = Arc::clone(shared);
+        move |bytes, binary| shared.admit(|| receive(&shared, channel, bytes, binary))
+    });
+    data_channel.on_state_change({
+        let shared = Arc::clone(shared);
+        move |state| {
+            shared.admit(|| {
+                let open = match state {
+                    DataChannelState::Open => true,
+                    DataChannelState::Closed => false,
+                    DataChannelState::Connecting | DataChannelState::Closing => return,
+                };
+                shared.emit(&Event::Channel { channel, open });
+            });
+        }
+    });
+    Ok(data_channel)
+}
+
+/// Pass a message to the host. The bridge's channels carry binary messages
+/// within the local bound; anything else fails the connection.
+fn receive(shared: &Shared, channel: Channel, bytes: &[u8], binary: bool) {
+    let label = channel.label();
+    if !binary {
+        shared.emit_error(
+            FailureClass::Protocol,
+            &format!("{label} data channel delivered a nonbinary message"),
+        );
+    } else if bytes.len() > MAX_MESSAGE_BYTES {
+        shared.emit_error(
+            FailureClass::Overflow,
+            &format!("{label} data channel message exceeds local bound"),
+        );
+    } else {
+        shared.emit(&Event::Message { channel, bytes });
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::abi::Status;
+    use crate::sync::Taken;
+    use crate::test_support::parse_packet;
+    use serde_json::{Value, json};
+
+    fn next_event(shared: &Shared) -> (Value, Vec<u8>) {
+        let Taken::Item(packet) = shared.events.take(|_| true) else {
+            panic!("an event must be queued");
+        };
+        let (header, payload) = parse_packet(&packet);
+        (header, payload.to_vec())
+    }
+
+    #[test]
+    fn a_binary_message_within_the_bound_reaches_the_host_unchanged() {
+        let shared = Shared::new();
+        let message = vec![7; MAX_MESSAGE_BYTES];
+        receive(&shared, Channel::Control, &message, true);
+        let (header, payload) = next_event(&shared);
+        assert_eq!(header, json!({ "type": "message", "channel": "control" }));
+        assert_eq!(payload, message);
+    }
+
+    #[test]
+    fn a_text_or_oversized_message_fails_the_connection() {
+        let shared = Shared::new();
+        receive(&shared, Channel::Data, b"text", false);
+        receive(
+            &shared,
+            Channel::Data,
+            &vec![0; MAX_MESSAGE_BYTES + 1],
+            true,
+        );
+        let (text, _) = next_event(&shared);
+        assert_eq!(text["type"], "error");
+        assert_eq!(text["status"], Status::Protocol.code());
+        let (oversized, _) = next_event(&shared);
+        assert_eq!(oversized["status"], Status::Overflow.code());
+    }
+}

package/rust/src/peer/media.rs

@@ -0,0 +1,221 @@
+//! Decoded media: the items the media queues hold, and the sinks that copy
+//! each frame libwebrtc decodes into them.
+
+use super::Shared;
+use crate::ffi::{ReactorEffectAudioHeader, ReactorEffectVideoHeader};
+use crate::protocol::TrackKind;
+use crate::sync::QueueItem;
+use reactor_webrtc::{AudioFrame, RemoteTrack, VideoFrame};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+/// One decoded BGRA frame and its sender metadata.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct VideoItem {
+    /// The track's index in the prepare request.
+    pub(crate) track: u32,
+    pub(crate) width: u32,
+    pub(crate) height: u32,
+    /// 0 when the sender supplied none.
+    pub(crate) frame_id: u64,
+    /// The sender's capture time; 0 when absent.
+    pub(crate) timestamp_us: u64,
+    /// The frame's admission sequence on its track.
+    pub(crate) sequence: u64,
+    pub(crate) bgra: Vec<u8>,
+    pub(crate) metadata: Vec<u8>,
+}
+
+impl VideoItem {
+    /// Copy a frame that libwebrtc lends only for the duration of its
+    /// callback. This is the one native copy of each frame.
+    fn copy(track: u32, sequence: u64, frame: VideoFrame<'_>) -> Self {
+        let (frame_id, timestamp_us, metadata) = frame
+            .metadata
+            .map(|metadata| {
+                (
+                    metadata.frame_id,
+                    metadata.capture_time_us,
+                    metadata.user_data,
+                )
+            })
+            .unwrap_or_default();
+        Self {
+            track,
+            width: frame.width,
+            height: frame.height,
+            frame_id,
+            timestamp_us,
+            sequence,
+            bgra: frame.bgra.to_vec(),
+            metadata,
+        }
+    }
+
+    pub(crate) fn header(&self) -> ReactorEffectVideoHeader {
+        ReactorEffectVideoHeader {
+            width: self.width,
+            height: self.height,
+            data_len: queued_len(self.bgra.len()),
+            metadata_len: queued_len(self.metadata.len()),
+            frame_id: self.frame_id,
+            timestamp_us: self.timestamp_us,
+            track: self.track,
+            reserved: 0,
+            sequence: self.sequence,
+        }
+    }
+}
+
+impl QueueItem for VideoItem {
+    fn byte_len(&self) -> usize {
+        self.bgra.len() + self.metadata.len()
+    }
+}
+
+/// One block of decoded, interleaved PCM.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct AudioItem {
+    /// The track's index in the prepare request.
+    pub(crate) track: u32,
+    pub(crate) sample_rate: u32,
+    pub(crate) channels: u32,
+    /// The block's admission sequence on its track.
+    pub(crate) sequence: u64,
+    pub(crate) pcm: Vec<i16>,
+}
+
+impl AudioItem {
+    /// Copy a block that libwebrtc lends only for the duration of its callback.
+    fn copy(track: u32, sequence: u64, frame: &AudioFrame<'_>) -> Self {
+        Self {
+            track,
+            sample_rate: frame.sample_rate,
+            channels: frame.channels,
+            sequence,
+            pcm: frame.pcm.to_vec(),
+        }
+    }
+
+    pub(crate) fn header(&self) -> ReactorEffectAudioHeader {
+        ReactorEffectAudioHeader {
+            sample_rate: self.sample_rate,
+            channels: self.channels,
+            samples: queued_len(self.pcm.len()),
+            track: self.track,
+            sequence: self.sequence,
+        }
+    }
+}
+
+impl QueueItem for AudioItem {
+    fn byte_len(&self) -> usize {
+        size_of_val(self.pcm.as_slice())
+    }
+}
+
+/// A length for a C header. Only queued items get headers, and a queue refuses
+/// any item over its byte bound, which `Shared` keeps within `u32`: the
+/// saturation never happens.
+fn queued_len(len: usize) -> u32 {
+    u32::try_from(len).unwrap_or(u32::MAX)
+}
+
+pub(crate) fn kind_of(track: &RemoteTrack) -> TrackKind {
+    match track {
+        RemoteTrack::Video(_) => TrackKind::Video,
+        RemoteTrack::Audio(_) => TrackKind::Audio,
+    }
+}
+
+/// Copy a remote track's decoded frames into the media queues, labelled with
+/// the declared track's index and numbered in admission order. The number is
+/// taken before the queue can drop the frame, so a reader sees each drop as a
+/// gap. libwebrtc delivers one track's frames on one thread, in order.
+pub(crate) fn route(track: &RemoteTrack, index: u32, shared: &Arc<Shared>) {
+    let shared = Arc::clone(shared);
+    let admitted = AtomicU64::new(0);
+    match track {
+        RemoteTrack::Video(video) => video.on_frame(move |frame| {
+            let sequence = admitted.fetch_add(1, Ordering::Relaxed);
+            shared.admit(|| shared.push_video(VideoItem::copy(index, sequence, frame)));
+        }),
+        RemoteTrack::Audio(audio) => audio.on_frame(move |frame| {
+            let sequence = admitted.fetch_add(1, Ordering::Relaxed);
+            shared.admit(|| shared.push_audio(AudioItem::copy(index, sequence, &frame)));
+        }),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn media_items_count_their_payload_bytes() {
+        let video = VideoItem {
+            track: 0,
+            width: 2,
+            height: 1,
+            frame_id: 0,
+            timestamp_us: 0,
+            sequence: 0,
+            bgra: vec![0; 8],
+            metadata: vec![0; 3],
+        };
+        let audio = AudioItem {
+            track: 1,
+            sample_rate: 48_000,
+            channels: 2,
+            sequence: 0,
+            pcm: vec![0; 480],
+        };
+        assert_eq!(video.byte_len(), 11);
+        assert_eq!(audio.byte_len(), 960, "samples are two bytes each");
+    }
+
+    #[test]
+    fn headers_describe_the_queued_payload() {
+        let video = VideoItem {
+            track: 3,
+            width: 2,
+            height: 1,
+            frame_id: u64::MAX,
+            timestamp_us: 9_007_199_254_740_993,
+            sequence: 41,
+            bgra: vec![0x21; 8],
+            metadata: b"meta".to_vec(),
+        };
+        assert_eq!(
+            video.header(),
+            ReactorEffectVideoHeader {
+                width: 2,
+                height: 1,
+                data_len: 8,
+                metadata_len: 4,
+                frame_id: u64::MAX,
+                timestamp_us: 9_007_199_254_740_993,
+                track: 3,
+                reserved: 0,
+                sequence: 41,
+            }
+        );
+        let audio = AudioItem {
+            track: 1,
+            sample_rate: 48_000,
+            channels: 2,
+            sequence: 7,
+            pcm: vec![0; 960],
+        };
+        assert_eq!(
+            audio.header(),
+            ReactorEffectAudioHeader {
+                sample_rate: 48_000,
+                channels: 2,
+                samples: 960,
+                track: 1,
+                sequence: 7,
+            }
+        );
+    }
+}

package/rust/src/peer/owner/tests.rs

@@ -0,0 +1,188 @@
+use super::*;
+use crate::protocol::TrackKind;
+use crate::sync::Taken;
+use serde_json::{Value, json};
+
+fn owner() -> Owner {
+    Owner::new(Arc::new(Shared::new()))
+}
+
+fn prepare_request(tracks: &Value) -> Vec<u8> {
+    serde_json::to_vec(&json!({ "servers": [], "tracks": tracks })).unwrap()
+}
+
+/// An owner prepared with one receive and one send track.
+fn prepared() -> Owner {
+    let mut owner = owner();
+    owner
+        .prepare(&prepare_request(&json!([
+            { "name": "in", "kind": "video", "direction": "recvonly" },
+            { "name": "out", "kind": "video", "direction": "sendonly" },
+        ])))
+        .expect("prepare");
+    owner
+}
+
+#[test]
+fn prepare_offers_every_track_and_maps_each_to_its_mid_in_request_order() {
+    let mut owner = owner();
+    let response = owner
+        .prepare(&prepare_request(&json!([
+            { "name": "video", "kind": "video", "direction": "recvonly" },
+            { "name": "audio", "kind": "audio", "direction": "recvonly" },
+            { "name": "camera", "kind": "video", "direction": "sendonly" },
+        ])))
+        .expect("prepare");
+    let response: Value = serde_json::from_slice(&response).unwrap();
+    let sdp = response["sdp"].as_str().unwrap();
+    assert!(sdp.contains("m=video") && sdp.contains("m=audio"), "{sdp}");
+    let mapping: Vec<Mapping> = serde_json::from_value(response["mapping"].clone()).unwrap();
+    let declared: Vec<_> = mapping
+        .iter()
+        .map(|entry| (entry.name.as_str(), entry.kind, entry.direction))
+        .collect();
+    assert_eq!(
+        declared,
+        [
+            ("video", TrackKind::Video, Direction::RecvOnly),
+            ("audio", TrackKind::Audio, Direction::RecvOnly),
+            ("camera", TrackKind::Video, Direction::SendOnly),
+        ]
+    );
+    for entry in &mapping {
+        assert!(sdp.contains(&format!("a=mid:{}", entry.mid)), "{entry:?}");
+    }
+    owner.shutdown();
+}
+
+#[test]
+fn a_peer_prepares_once() {
+    let mut owner = prepared();
+    let error = owner.prepare(&prepare_request(&json!([]))).unwrap_err();
+    assert_eq!(
+        error,
+        BridgeError::invalid("native peer is already prepared")
+    );
+    owner.shutdown();
+}
+
+#[test]
+fn a_rejected_answer_is_classified_as_sdp_rejected() {
+    let owner = prepared();
+    let error = owner
+        .answer(b"v=0\r\nthis is not an answer\r\n")
+        .expect_err("libwebrtc must reject a malformed answer");
+    assert_eq!(error.class, FailureClass::SdpRejected);
+    assert!(
+        error.message.starts_with("set_remote_description: "),
+        "{error}"
+    );
+    owner.shutdown();
+}
+
+#[test]
+fn an_empty_or_non_utf8_answer_is_invalid_input() {
+    let owner = prepared();
+    assert_eq!(
+        owner.answer(b"").unwrap_err(),
+        BridgeError::invalid("answer SDP is empty")
+    );
+    let error = owner.answer(&[0xff, 0xfe]).unwrap_err();
+    assert_eq!(error.class, FailureClass::InvalidInput);
+    assert!(
+        error.message.starts_with("answer SDP is not UTF-8: "),
+        "{error}"
+    );
+    owner.shutdown();
+}
+
+#[test]
+fn before_prepare_each_call_fails_with_its_class() {
+    let owner = owner();
+    assert_eq!(owner.answer(b"v=0").unwrap_err(), BridgeError::closed());
+    assert_eq!(owner.stats().unwrap_err(), BridgeError::closed());
+    let error = owner
+        .set_direction(br#"{"name":"out","active":false}"#)
+        .unwrap_err();
+    assert_eq!(error, BridgeError::invalid("unknown track: out"));
+    let error = owner.send(Channel::Data, b"early").unwrap_err();
+    assert_eq!(
+        error,
+        BridgeError::new(FailureClass::ChannelClosed, "data channel is not open")
+    );
+    owner.shutdown();
+}
+
+#[test]
+fn a_declared_track_pauses_resumes_and_caps_its_bitrate() {
+    let owner = prepared();
+    for request in [
+        br#"{"name":"out","active":false}"#.as_slice(),
+        br#"{"name":"out","active":true}"#,
+        br#"{"name":"in","active":false}"#,
+        br#"{"name":"in","active":true}"#,
+    ] {
+        let response = owner.set_direction(request).expect("direction");
+        assert_eq!(response, b"{}");
+    }
+    let response = owner
+        .set_max_bitrate(br#"{"name":"out","bitsPerSecond":2000000}"#)
+        .expect("bitrate");
+    assert_eq!(response, b"{}");
+    owner.shutdown();
+}
+
+#[test]
+fn only_a_declared_sending_track_takes_a_bitrate() {
+    let owner = prepared();
+    assert_eq!(
+        owner
+            .set_max_bitrate(br#"{"name":"in","bitsPerSecond":1000}"#)
+            .unwrap_err(),
+        BridgeError::invalid("in is not an outgoing track")
+    );
+    assert_eq!(
+        owner
+            .set_max_bitrate(br#"{"name":"missing","bitsPerSecond":1000}"#)
+            .unwrap_err(),
+        BridgeError::invalid("unknown track: missing")
+    );
+    assert_eq!(
+        owner
+            .set_direction(br#"{"name":"missing","active":true}"#)
+            .unwrap_err(),
+        BridgeError::invalid("unknown track: missing")
+    );
+    owner.shutdown();
+}
+
+#[test]
+fn a_prepared_peer_reports_stats_before_it_connects() {
+    let owner = prepared();
+    let stats: Value = serde_json::from_slice(&owner.stats().expect("stats")).unwrap();
+    assert!(stats.is_array(), "{stats}");
+    owner.shutdown();
+}
+
+#[test]
+fn commands_queued_behind_close_are_refused() {
+    let mut owner = prepared();
+    owner.shared.close();
+    let refused = owner
+        .unless_closed(|_| -> Result<(), BridgeError> { panic!("a closed peer runs no command") });
+    assert_eq!(refused, Err(BridgeError::closed()));
+    owner.shutdown();
+}
+
+#[test]
+fn shutdown_closes_every_queue() {
+    let shared = Arc::new(Shared::new());
+    let mut owner = Owner::new(Arc::clone(&shared));
+    owner
+        .prepare(&prepare_request(&json!([])))
+        .expect("prepare");
+    owner.shutdown();
+    assert_eq!(shared.events.take(|_| true), Taken::Closed);
+    assert_eq!(shared.video.take(|_| true), Taken::Closed);
+    assert_eq!(shared.audio.take(|_| true), Taken::Closed);
+}