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

package/rust/src/protocol/stats.rs

@@ -0,0 +1,356 @@
+//! The `Stats` and `MediaSnapshot` responses.
+
+use super::DecimalU64;
+use reactor_webrtc::{
+    IceCandidatePairState, IceCandidateType, RelayProtocol, StatsReport, StreamKind,
+};
+use serde::Serialize;
+use serde_json::{Value, json};
+
+/// The `Stats` response: an `RTCStatsReport`-shaped array with an entry per
+/// inbound and outbound RTP stream and, per ICE candidate pair, the pair and
+/// its local candidate. The host reads the pairs to tell an ICE failure from
+/// a transport failure above it.
+pub(crate) fn stats_json(report: &StatsReport) -> Value {
+    let inbound = report.inbound_rtp.iter().map(|entry| {
+        json!({
+            "id": format!("inbound-rtp-{}", entry.ssrc),
+            "type": "inbound-rtp",
+            "ssrc": entry.ssrc,
+            "kind": stream_kind(entry.kind),
+            "packetsReceived": entry.packets_received,
+            "bytesReceived": DecimalU64(entry.bytes_received),
+            "jitter": entry.jitter_s,
+            "packetsLost": entry.packets_lost,
+            "nackCount": entry.nack_count,
+            "pliCount": entry.pli_count,
+            "firCount": entry.fir_count,
+            "totalDecodeTime": entry.total_decode_time_s,
+            "framesPerSecond": entry.frames_per_second,
+            "framesDecoded": entry.frames_decoded,
+            "framesDropped": entry.frames_dropped,
+            "frameWidth": entry.frame_width,
+            "frameHeight": entry.frame_height,
+        })
+    });
+    let outbound = report.outbound_rtp.iter().map(|entry| {
+        json!({
+            "id": format!("outbound-rtp-{}", entry.ssrc),
+            "type": "outbound-rtp",
+            "ssrc": entry.ssrc,
+            "kind": stream_kind(entry.kind),
+            "packetsSent": DecimalU64(entry.packets_sent),
+            "bytesSent": DecimalU64(entry.bytes_sent),
+            "targetBitrate": entry.target_bitrate_bps,
+            "roundTripTime": entry.round_trip_time_s,
+            "totalRoundTripTime": entry.total_round_trip_time_s,
+            "fractionLost": entry.fraction_lost,
+            "packetsLost": entry.packets_lost,
+            "retransmittedPacketsSent": DecimalU64(entry.retransmitted_packets_sent),
+            "nackCount": entry.nack_count,
+            "pliCount": entry.pli_count,
+            "firCount": entry.fir_count,
+            "framesPerSecond": entry.frames_per_second,
+            "framesSent": entry.frames_sent,
+            "frameWidth": entry.frame_width,
+            "frameHeight": entry.frame_height,
+        })
+    });
+    let pairs = report
+        .candidate_pairs
+        .iter()
+        .enumerate()
+        .flat_map(|(index, pair)| {
+            let local_id = format!("local-candidate-{index}");
+            [
+                json!({
+                    "id": local_id,
+                    "type": "local-candidate",
+                    "candidateType": candidate_type(pair.local_candidate_type),
+                    "relayProtocol": relay_protocol(pair.local_relay_protocol),
+                }),
+                json!({
+                    "id": format!("candidate-pair-{index}"),
+                    "type": "candidate-pair",
+                    "state": pair_state(pair.state),
+                    "nominated": pair.nominated,
+                    "writable": pair.writable,
+                    "priority": DecimalU64(pair.priority),
+                    "bytesSent": DecimalU64(pair.bytes_sent),
+                    "bytesReceived": DecimalU64(pair.bytes_received),
+                    "packetsSent": DecimalU64(pair.packets_sent),
+                    "packetsReceived": DecimalU64(pair.packets_received),
+                    "currentRoundTripTime": pair.current_round_trip_time_s,
+                    "totalRoundTripTime": pair.total_round_trip_time_s,
+                    "availableOutgoingBitrate": pair.available_outgoing_bitrate_bps,
+                    "availableIncomingBitrate": pair.available_incoming_bitrate_bps,
+                    "localCandidateId": local_id,
+                }),
+            ]
+        });
+    inbound.chain(outbound).chain(pairs).collect()
+}
+
+fn stream_kind(kind: StreamKind) -> &'static str {
+    match kind {
+        StreamKind::Audio => "audio",
+        StreamKind::Video => "video",
+        StreamKind::Unknown => "unknown",
+    }
+}
+
+fn pair_state(state: IceCandidatePairState) -> &'static str {
+    match state {
+        IceCandidatePairState::Waiting => "waiting",
+        IceCandidatePairState::InProgress => "in-progress",
+        IceCandidatePairState::Failed => "failed",
+        IceCandidatePairState::Succeeded => "succeeded",
+        IceCandidatePairState::Cancelled => "cancelled",
+    }
+}
+
+fn candidate_type(kind: IceCandidateType) -> &'static str {
+    match kind {
+        IceCandidateType::Host => "host",
+        IceCandidateType::Srflx => "srflx",
+        IceCandidateType::Prflx => "prflx",
+        IceCandidateType::Relay => "relay",
+        IceCandidateType::Unknown => "unknown",
+    }
+}
+
+fn relay_protocol(protocol: RelayProtocol) -> &'static str {
+    match protocol {
+        RelayProtocol::Udp => "udp",
+        RelayProtocol::Tcp => "tcp",
+        RelayProtocol::Tls => "tls",
+        RelayProtocol::NotRelayed => "",
+    }
+}
+
+/// The `MediaSnapshot` response: what each queue dropped, delivered and still
+/// holds.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct MediaSnapshot {
+    pub(crate) closed: bool,
+    pub(crate) queued_control: usize,
+    pub(crate) queued_video: usize,
+    pub(crate) queued_audio: usize,
+    pub(crate) queued_bytes: usize,
+    pub(crate) dropped_video: DecimalU64,
+    pub(crate) dropped_audio: DecimalU64,
+    pub(crate) delivered_video: DecimalU64,
+    pub(crate) delivered_audio: DecimalU64,
+    /// Always 0: calls wait on the owner thread, never in a native queue.
+    pub(crate) pending_requests: usize,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use reactor_webrtc::{IceCandidatePairStats, InboundRtpStats, OutboundRtpStats};
+
+    const BEYOND_DOUBLES: u64 = (1 << 53) + 1;
+
+    fn report() -> StatsReport {
+        StatsReport {
+            inbound_rtp: vec![InboundRtpStats {
+                ssrc: 11,
+                kind: StreamKind::Video,
+                packets_received: 5,
+                bytes_received: BEYOND_DOUBLES,
+                jitter_s: 0.25,
+                packets_lost: -1,
+                nack_count: 2,
+                pli_count: 3,
+                fir_count: 4,
+                total_decode_time_s: 1.5,
+                frames_per_second: 24.0,
+                frames_decoded: 90,
+                frames_dropped: 1,
+                frame_width: 64,
+                frame_height: 48,
+            }],
+            outbound_rtp: vec![OutboundRtpStats {
+                ssrc: 22,
+                kind: StreamKind::Audio,
+                packets_sent: 6,
+                bytes_sent: 7,
+                target_bitrate_bps: 32_000.0,
+                round_trip_time_s: 0.5,
+                total_round_trip_time_s: 2.0,
+                fraction_lost: 0.125,
+                packets_lost: 8,
+                retransmitted_packets_sent: 9,
+                nack_count: 10,
+                pli_count: 0,
+                fir_count: 0,
+                frames_per_second: 0.0,
+                frames_sent: 0,
+                frame_width: 0,
+                frame_height: 0,
+            }],
+            candidate_pairs: vec![IceCandidatePairStats {
+                current_round_trip_time_s: 0.25,
+                total_round_trip_time_s: 0.75,
+                priority: u64::MAX,
+                state: IceCandidatePairState::Succeeded,
+                nominated: true,
+                writable: true,
+                available_outgoing_bitrate_bps: 1_000_000.0,
+                available_incoming_bitrate_bps: 0.0,
+                bytes_sent: 12,
+                bytes_received: 13,
+                packets_sent: 14,
+                packets_received: 15,
+                local_candidate_type: IceCandidateType::Relay,
+                local_relay_protocol: RelayProtocol::Tls,
+            }],
+        }
+    }
+
+    // `connectionFailure` and `statsValue` in packages/native/src/_internal/peer.ts
+    // read these entries; every counter in its `statsBigInts` travels as a
+    // decimal string.
+    #[test]
+    fn stats_have_the_entries_and_keys_the_host_reads() {
+        assert_eq!(
+            stats_json(&report()),
+            json!([
+                {
+                    "id": "inbound-rtp-11",
+                    "type": "inbound-rtp",
+                    "ssrc": 11,
+                    "kind": "video",
+                    "packetsReceived": 5,
+                    "bytesReceived": "9007199254740993",
+                    "jitter": 0.25,
+                    "packetsLost": -1,
+                    "nackCount": 2,
+                    "pliCount": 3,
+                    "firCount": 4,
+                    "totalDecodeTime": 1.5,
+                    "framesPerSecond": 24.0,
+                    "framesDecoded": 90,
+                    "framesDropped": 1,
+                    "frameWidth": 64,
+                    "frameHeight": 48,
+                },
+                {
+                    "id": "outbound-rtp-22",
+                    "type": "outbound-rtp",
+                    "ssrc": 22,
+                    "kind": "audio",
+                    "packetsSent": "6",
+                    "bytesSent": "7",
+                    "targetBitrate": 32_000.0,
+                    "roundTripTime": 0.5,
+                    "totalRoundTripTime": 2.0,
+                    "fractionLost": 0.125,
+                    "packetsLost": 8,
+                    "retransmittedPacketsSent": "9",
+                    "nackCount": 10,
+                    "pliCount": 0,
+                    "firCount": 0,
+                    "framesPerSecond": 0.0,
+                    "framesSent": 0,
+                    "frameWidth": 0,
+                    "frameHeight": 0,
+                },
+                {
+                    "id": "local-candidate-0",
+                    "type": "local-candidate",
+                    "candidateType": "relay",
+                    "relayProtocol": "tls",
+                },
+                {
+                    "id": "candidate-pair-0",
+                    "type": "candidate-pair",
+                    "state": "succeeded",
+                    "nominated": true,
+                    "writable": true,
+                    "priority": "18446744073709551615",
+                    "bytesSent": "12",
+                    "bytesReceived": "13",
+                    "packetsSent": "14",
+                    "packetsReceived": "15",
+                    "currentRoundTripTime": 0.25,
+                    "totalRoundTripTime": 0.75,
+                    "availableOutgoingBitrate": 1_000_000.0,
+                    "availableIncomingBitrate": 0.0,
+                    "localCandidateId": "local-candidate-0",
+                },
+            ])
+        );
+    }
+
+    #[test]
+    fn an_empty_report_is_an_empty_array() {
+        assert_eq!(stats_json(&StatsReport::default()), json!([]));
+    }
+
+    #[test]
+    fn every_pair_state_candidate_type_and_relay_protocol_has_a_stats_name() {
+        let states = [
+            IceCandidatePairState::Waiting,
+            IceCandidatePairState::InProgress,
+            IceCandidatePairState::Failed,
+            IceCandidatePairState::Succeeded,
+            IceCandidatePairState::Cancelled,
+        ]
+        .map(pair_state);
+        assert_eq!(
+            states,
+            ["waiting", "in-progress", "failed", "succeeded", "cancelled"]
+        );
+        let types = [
+            IceCandidateType::Host,
+            IceCandidateType::Srflx,
+            IceCandidateType::Prflx,
+            IceCandidateType::Relay,
+            IceCandidateType::Unknown,
+        ]
+        .map(candidate_type);
+        assert_eq!(types, ["host", "srflx", "prflx", "relay", "unknown"]);
+        let protocols = [
+            RelayProtocol::Udp,
+            RelayProtocol::Tcp,
+            RelayProtocol::Tls,
+            RelayProtocol::NotRelayed,
+        ]
+        .map(relay_protocol);
+        assert_eq!(protocols, ["udp", "tcp", "tls", ""]);
+    }
+
+    #[test]
+    fn a_snapshot_has_the_keys_the_host_parses() {
+        let snapshot = MediaSnapshot {
+            closed: false,
+            queued_control: 1,
+            queued_video: 2,
+            queued_audio: 3,
+            queued_bytes: 4,
+            dropped_video: DecimalU64(BEYOND_DOUBLES),
+            dropped_audio: DecimalU64(5),
+            delivered_video: DecimalU64(6),
+            delivered_audio: DecimalU64(7),
+            pending_requests: 0,
+        };
+        assert_eq!(
+            serde_json::to_value(&snapshot).unwrap(),
+            json!({
+                "closed": false,
+                "queuedControl": 1,
+                "queuedVideo": 2,
+                "queuedAudio": 3,
+                "queuedBytes": 4,
+                "droppedVideo": "9007199254740993",
+                "droppedAudio": "5",
+                "deliveredVideo": "6",
+                "deliveredAudio": "7",
+                "pendingRequests": 0,
+            })
+        );
+    }
+}

package/rust/src/protocol.rs

@@ -0,0 +1,71 @@
+//! The JSON the bridge exchanges with its host: call requests and responses,
+//! and the headers of transport events.
+
+mod event;
+mod request;
+mod stats;
+
+pub(crate) use event::{Event, LocalCandidate, connection_state};
+pub(crate) use request::{
+    BitrateRequest, Direction, DirectionRequest, Mapping, PrepareRequest, PrepareResponse,
+    TrackKind,
+};
+pub(crate) use stats::{MediaSnapshot, stats_json};
+
+use crate::error::{BridgeError, FailureClass};
+use serde::de::DeserializeOwned;
+use serde::{Serialize, Serializer};
+
+/// A `u64` for the JavaScript host, which reads JSON numbers as doubles and
+/// would round counters past 2^53, so it travels as a decimal string.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct DecimalU64(pub(crate) u64);
+
+impl Serialize for DecimalU64 {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.collect_str(&self.0)
+    }
+}
+
+/// Decode a JSON request. Any failure is invalid input.
+pub(crate) fn decode<T: DeserializeOwned>(request: &[u8]) -> Result<T, BridgeError> {
+    serde_json::from_slice(request)
+        .map_err(|error| BridgeError::invalid(format!("invalid JSON: {error}")))
+}
+
+/// Encode a JSON response or event header.
+pub(crate) fn encode(value: &impl Serialize) -> Result<Vec<u8>, BridgeError> {
+    serde_json::to_vec(value)
+        .map_err(|error| BridgeError::new(FailureClass::Native, format!("serialize JSON: {error}")))
+}
+
+/// The response of a call that returns nothing.
+pub(crate) fn empty_response() -> Vec<u8> {
+    b"{}".to_vec()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn counters_beyond_double_precision_travel_as_exact_decimal_strings() {
+        let counters = [
+            DecimalU64(0),
+            DecimalU64(9_007_199_254_740_993),
+            DecimalU64(u64::MAX),
+        ];
+        assert_eq!(
+            serde_json::to_value(counters).unwrap(),
+            json!(["0", "9007199254740993", "18446744073709551615"])
+        );
+    }
+
+    #[test]
+    fn a_malformed_request_is_invalid_input() {
+        let error = decode::<Vec<u8>>(b"{").unwrap_err();
+        assert_eq!(error.class, FailureClass::InvalidInput);
+        assert!(error.message.starts_with("invalid JSON: "), "{error}");
+    }
+}

package/rust/src/sync/gate.rs

@@ -0,0 +1,159 @@
+//! Admission of libwebrtc callbacks, fenced by close and awaited by shutdown.
+
+use super::lock;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Condvar, Mutex, PoisonError};
+
+/// Admits libwebrtc callbacks until closed, and counts the admitted ones so
+/// shutdown can wait for every callback that is still running.
+pub(crate) struct CallbackGate {
+    open: AtomicBool,
+    running: Mutex<usize>,
+    idle: Condvar,
+}
+
+impl CallbackGate {
+    /// An open gate.
+    pub(crate) fn new() -> Self {
+        Self {
+            open: AtomicBool::new(true),
+            running: Mutex::new(0),
+            idle: Condvar::new(),
+        }
+    }
+
+    /// Whether the gate still admits callbacks and host calls.
+    pub(crate) fn is_open(&self) -> bool {
+        self.open.load(Ordering::Acquire)
+    }
+
+    /// Admit one callback, or refuse it once the gate has closed. The callback
+    /// counts as running until the guard drops.
+    pub(crate) fn enter(&self) -> Option<CallbackGuard<'_>> {
+        if !self.is_open() {
+            return None;
+        }
+        let mut running = lock(&self.running);
+        // `wait_idle` takes this lock after `close`, so re-checking under it
+        // means a callback is either refused or counted before anyone waits.
+        if !self.is_open() {
+            return None;
+        }
+        *running += 1;
+        Some(CallbackGuard { gate: self })
+    }
+
+    /// Stop admitting callbacks. Callbacks already admitted keep running.
+    pub(crate) fn close(&self) {
+        self.open.store(false, Ordering::Release);
+    }
+
+    /// Block until no admitted callback is running. Called after [`close`],
+    /// it returns once no callback can run again.
+    ///
+    /// [`close`]: Self::close
+    pub(crate) fn wait_idle(&self) {
+        let _idle = self
+            .idle
+            .wait_while(lock(&self.running), |running| *running > 0)
+            .unwrap_or_else(PoisonError::into_inner);
+    }
+}
+
+impl Default for CallbackGate {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// One admitted callback. Dropping it lets a waiting shutdown proceed.
+pub(crate) struct CallbackGuard<'gate> {
+    gate: &'gate CallbackGate,
+}
+
+impl Drop for CallbackGuard<'_> {
+    fn drop(&mut self) {
+        let mut running = lock(&self.gate.running);
+        *running -= 1;
+        if *running == 0 {
+            self.gate.idle.notify_all();
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::test_support::{Defer, wait_until};
+    use std::sync::atomic::AtomicUsize;
+    use std::thread;
+    use std::time::Duration;
+
+    #[test]
+    fn close_refuses_new_callbacks_and_wait_idle_waits_for_admitted_ones() {
+        let gate = CallbackGate::new();
+        let guard = gate.enter().expect("an open gate admits");
+        gate.close();
+        assert!(!gate.is_open());
+        assert!(gate.enter().is_none(), "a closed gate must refuse");
+
+        thread::scope(|scope| {
+            let waiter = scope.spawn(|| gate.wait_idle());
+            thread::sleep(Duration::from_millis(10));
+            assert!(
+                !waiter.is_finished(),
+                "wait_idle returned while a callback was running"
+            );
+            drop(guard);
+            waiter.join().unwrap();
+        });
+    }
+
+    #[test]
+    fn wait_idle_returns_at_once_when_nothing_was_admitted() {
+        let gate = CallbackGate::default();
+        gate.close();
+        gate.wait_idle();
+    }
+
+    #[test]
+    fn no_callback_runs_once_close_and_wait_idle_return() {
+        let gate = CallbackGate::new();
+        let running = AtomicUsize::new(0);
+        let admitted = AtomicUsize::new(0);
+        let stop = AtomicBool::new(false);
+        thread::scope(|scope| {
+            let _stop_callers = Defer(|| stop.store(true, Ordering::Relaxed));
+            for _ in 0..4 {
+                scope.spawn(|| {
+                    while !stop.load(Ordering::Relaxed) {
+                        if let Some(_guard) = gate.enter() {
+                            running.fetch_add(1, Ordering::SeqCst);
+                            admitted.fetch_add(1, Ordering::Relaxed);
+                            thread::yield_now();
+                            running.fetch_sub(1, Ordering::SeqCst);
+                        }
+                    }
+                });
+            }
+            wait_until("admitted callbacks", Duration::from_secs(5), || {
+                admitted.load(Ordering::Relaxed) >= 1_000
+            });
+
+            gate.close();
+            gate.wait_idle();
+            assert_eq!(
+                running.load(Ordering::SeqCst),
+                0,
+                "a callback outlived wait_idle"
+            );
+            let admitted_at_close = admitted.load(Ordering::SeqCst);
+            thread::sleep(Duration::from_millis(5));
+            assert_eq!(
+                admitted.load(Ordering::SeqCst),
+                admitted_at_close,
+                "a callback was admitted after close"
+            );
+        });
+    }
+}