@desklink/host 0.5.7 → 0.5.9

package/engine/src/peer.rs

@@ -23,7 +23,7 @@ use rtc::peer_connection::configuration::media_engine::{
 use rtc::peer_connection::configuration::RTCConfigurationBuilder;
 use rtc::peer_connection::event::RTCPeerConnectionIceEvent;
 use rtc::peer_connection::sdp::RTCSessionDescription;
-use rtc::peer_connection::transport::{RTCIceCandidateInit, RTCIceServer};
+use rtc::peer_connection::transport::{RTCIceCandidateInit, RTCIceProtocol, RTCIceServer};
 use rtc::rtcp::payload_feedbacks::full_intra_request::FullIntraRequest;
 use rtc::rtcp::payload_feedbacks::picture_loss_indication::PictureLossIndication;
 use rtc::rtcp::receiver_report::ReceiverReport;
@@ -47,7 +47,7 @@ use webrtc::peer_connection::{
 };
 use webrtc::runtime::default_runtime;
 
-// desklink scout trace (dl-roam-postnom-attr): engine-side restart timeline.
+// desklink scout trace: engine-side restart timeline.
 // Enabled with `DESKLINK_ICE_TRACE=1`; stamps microseconds since the Unix epoch
 // so these lines interleave with the vendored ICE agent's `[ice ...]` lines in
 // one order. Droppable: grep `desklink scout trace`.
@@ -258,7 +258,10 @@ pub enum PeerEvent {
 /// Transport settings the consumer chose for this session.
 #[derive(Debug, Clone)]
 pub struct TransportOptions {
-    pub ice_servers: Vec<(String, Option<String>, Option<String>)>,
+    /// One entry per ICE server the consumer asked for, carrying every URL
+    /// that entry listed; the engine has already left out the ones the
+    /// WebRTC stack cannot dial and reported those to the consumer.
+    pub ice_servers: Vec<(Vec<String>, Option<String>, Option<String>)>,
     /// Listen for ICE over TCP on the loopback too. A phone that reaches this
     /// computer only through SSH has no UDP path; it forwards this port over
     /// the SSH connection it already has, and the picture rides that.
@@ -267,6 +270,33 @@ pub struct TransportOptions {
     pub pace_bps: f64,
 }
 
+/// The UDP sockets ICE gathers host candidates from: an ephemeral port on every
+/// IPv4 interface and, when this computer has an IPv6 address a peer could
+/// reach, on every IPv6 one too. Mobile carriers commonly hand a phone a global
+/// IPv6 address, and a stateful firewall passes the simultaneous checks, so
+/// IPv6 can be the only direct path a phone off home Wi-Fi has. The library
+/// expands a wildcard into the interfaces' own addresses, skipping loopback and
+/// link-local; with none left it binds the wildcard itself and offers `::`,
+/// which no peer can use, so `[::]` is asked for only when there is one.
+fn udp_addrs() -> Vec<std::net::SocketAddr> {
+    let has_ipv6 = rtc::shared::ifaces::ifaces()
+        .unwrap_or_default()
+        .iter()
+        .filter_map(|interface| interface.addr)
+        .any(|addr| match addr.ip() {
+            std::net::IpAddr::V6(ip) => {
+                // fe80::/10; `Ipv6Addr::is_unicast_link_local` is still unstable.
+                !ip.is_loopback() && !ip.is_unspecified() && ip.segments()[0] & 0xffc0 != 0xfe80
+            }
+            std::net::IpAddr::V4(_) => false,
+        });
+    let mut addrs = vec![std::net::SocketAddr::from(([0, 0, 0, 0], 0))];
+    if has_ipv6 {
+        addrs.push(std::net::SocketAddr::from(([0u16; 8], 0)));
+    }
+    addrs
+}
+
 /// What the pacer lets go back to back: a few dozen packets. A 4K key frame is
 /// hundreds of packets, and released at once it overflows the receiver's
 /// socket buffer, which loses the frame and draws another key frame request —
@@ -447,7 +477,7 @@ impl PeerConnectionEventHandler for Handler {
     }
 
     async fn on_connection_state_change(&self, state: RTCPeerConnectionState) {
-        // desklink scout trace (dl-roam-postnom-attr): the engine's rtc-level
+        // desklink scout trace: the engine's rtc-level
         // transport state event, on the same microsecond clock as the vendored
         // agent's `[ice ...]` lines, so the rtc Connected gate is separable.
         if dl_trace_on() {
@@ -871,8 +901,8 @@ impl VideoPeer {
                 options
                     .ice_servers
                     .iter()
-                    .map(|(url, username, credential)| RTCIceServer {
-                        urls: vec![url.clone()],
+                    .map(|(urls, username, credential)| RTCIceServer {
+                        urls: urls.clone(),
                         username: username.clone().unwrap_or_default(),
                         credential: credential.clone().unwrap_or_default(),
                     })
@@ -899,7 +929,7 @@ impl VideoPeer {
             // An ephemeral port on every interface: ICE needs a socket to gather
             // candidates from, and the peer needs no fixed port because the
             // consumer's authenticated channel carries the candidates.
-            .with_udp_addrs(vec![std::net::SocketAddr::from(([0, 0, 0, 0], 0))])
+            .with_udp_addrs(udp_addrs())
             .with_tcp_addrs(if options.loopback_tcp {
                 vec![std::net::SocketAddr::from(([127, 0, 0, 1], 0))]
             } else {
@@ -1103,6 +1133,21 @@ impl VideoPeer {
         self.connected.load(Ordering::SeqCst)
     }
 
+    /// Whether ICE selected a TCP candidate pair (the relay's ICE-TCP path).
+    /// False until a pair is selected.
+    pub async fn selected_pair_is_tcp(&self) -> bool {
+        let Some(sender) = self.peer.get_senders().await.into_iter().next() else {
+            return false;
+        };
+        let Ok(Some(dtls)) = sender.transport().await else {
+            return false;
+        };
+        matches!(
+            dtls.ice_transport().get_selected_candidate_pair().await,
+            Ok(Some(pair)) if pair.local().protocol == RTCIceProtocol::Tcp
+        )
+    }
+
     /// Stand in for a connected transport, for a pipeline under test.
     #[cfg(test)]
     pub fn assume_connected(&self) {
@@ -1145,6 +1190,12 @@ impl VideoPeer {
         lock(&self.path).take()
     }
 
+    /// Stand in for transport-wide feedback that reports a path, for a pipeline under test.
+    #[cfg(test)]
+    pub fn report_path(&self, report: PathReport) {
+        *lock(&self.path) = Some(report);
+    }
+
     /// Take the pending "the far end needs a reference frame" request, if any.
     pub fn take_keyframe_request(&self) -> bool {
         self.wants_keyframe.swap(false, Ordering::SeqCst)
@@ -1258,7 +1309,7 @@ pub(crate) mod tests {
             .with_interceptor_registry(registry)
             .with_runtime(default_runtime().expect("a runtime"))
             .with_handler(Arc::new(NoopHandler))
-            .with_udp_addrs(vec![std::net::SocketAddr::from(([0, 0, 0, 0], 0))])
+            .with_udp_addrs(udp_addrs())
             .build()
             .await
             .expect("an answering peer");
@@ -1667,7 +1718,11 @@ pub(crate) mod tests {
         }
     }
 
-    async fn media_receiver(receiver: Arc<MediaReceiver>) -> Arc<dyn PeerConnection> {
+    async fn media_receiver(
+        receiver: Arc<MediaReceiver>,
+        udp: Vec<std::net::SocketAddr>,
+        tcp: Vec<std::net::SocketAddr>,
+    ) -> Arc<dyn PeerConnection> {
         let mut media_engine = MediaEngine::default();
         media_engine
             .register_codec(vp9_codec(), RtpCodecKind::Video)
@@ -1679,20 +1734,38 @@ pub(crate) mod tests {
             .with_interceptor_registry(registry)
             .with_runtime(default_runtime().expect("a runtime"))
             .with_handler(receiver)
-            .with_udp_addrs(vec![std::net::SocketAddr::from(([0, 0, 0, 0], 0))])
+            .with_udp_addrs(udp)
+            .with_tcp_addrs(tcp)
             .build()
             .await
             .expect("a receiving peer");
         Arc::new(peer)
     }
 
-    /// A restart offer/answer round must not interrupt media already flowing on
-    /// the selected pair: the picture keeps advancing (no gap over 200 ms) while
-    /// the old pair stays reachable, and the ICE generation still turns over.
-    #[tokio::test]
-    async fn a_restart_keeps_media_flowing_on_the_selected_pair_until_the_new_one_nominates() {
+    /// An engine and a client receiving on `client_udp`, offered, answered and
+    /// connected over ICE, with the client's RTP arrival times and the
+    /// candidates the engine offered.
+    pub(crate) struct Connected {
+        pub(crate) engine: Arc<VideoPeer>,
+        offer: String,
+        pub(crate) client: Arc<dyn PeerConnection>,
+        arrivals: Arc<Mutex<Vec<Instant>>>,
+        offered: Arc<Mutex<Vec<String>>>,
+    }
+
+    /// `client_tcp` and `loopback_tcp` give a pair that runs over ICE-TCP: a
+    /// client with no UDP candidates can only reach the engine over TCP.
+    pub(crate) async fn connected(
+        client_udp: Vec<std::net::SocketAddr>,
+        client_tcp: Vec<std::net::SocketAddr>,
+        loopback_tcp: bool,
+    ) -> Connected {
         let (events, mut events_rx) = tokio::sync::mpsc::unbounded_channel();
-        let (engine, offer) = VideoPeer::offer(transport(), events, VideoCodec::Vp9)
+        let options = TransportOptions {
+            loopback_tcp,
+            ..transport()
+        };
+        let (engine, offer) = VideoPeer::offer(options, events, VideoCodec::Vp9)
             .await
             .expect("an offering peer");
         let engine = Arc::new(engine);
@@ -1706,7 +1779,7 @@ pub(crate) mod tests {
             arrivals: Arc::clone(&arrivals),
             connected: Arc::clone(&connected),
         });
-        let client = media_receiver(Arc::clone(&receiver)).await;
+        let client = media_receiver(Arc::clone(&receiver), client_udp, client_tcp).await;
 
         client
             .set_remote_description(RTCSessionDescription::offer(offer.clone()).expect("an offer"))
@@ -1724,6 +1797,8 @@ pub(crate) mod tests {
 
         // The engine's candidates reach the client.
         let client_for_engine_candidates = Arc::clone(&client);
+        let offered: Arc<Mutex<Vec<String>>> = Arc::new(Mutex::new(Vec::new()));
+        let offered_by_engine = Arc::clone(&offered);
         tokio::spawn(async move {
             while let Some(event) = events_rx.recv().await {
                 if let PeerEvent::Candidate {
@@ -1732,6 +1807,7 @@ pub(crate) mod tests {
                     sdp_m_line_index,
                 } = event
                 {
+                    offered_by_engine.lock().unwrap().push(candidate.clone());
                     let _ = client_for_engine_candidates
                         .add_ice_candidate(RTCIceCandidateInit {
                             candidate,
@@ -1757,9 +1833,40 @@ pub(crate) mod tests {
         // Wait for the ICE path to come up on both ends.
         let deadline = Instant::now() + Duration::from_secs(5);
         while !(engine.is_connected() && connected.load(Ordering::SeqCst)) {
-            assert!(Instant::now() < deadline, "the peers never connected");
+            assert!(
+                Instant::now() < deadline,
+                "the peers never connected; the engine offered {:?}",
+                offered.lock().unwrap()
+            );
             tokio::time::sleep(Duration::from_millis(10)).await;
         }
+        Connected {
+            engine,
+            offer,
+            client,
+            arrivals,
+            offered,
+        }
+    }
+
+    /// A restart offer/answer round must not interrupt media already flowing on
+    /// the selected pair: the picture keeps advancing (no gap over 200 ms) while
+    /// the old pair stays reachable, and the ICE generation still turns over.
+    #[tokio::test]
+    async fn a_restart_keeps_media_flowing_on_the_selected_pair_until_the_new_one_nominates() {
+        let Connected {
+            engine,
+            offer,
+            client,
+            arrivals,
+            offered,
+        } = connected(
+            vec![std::net::SocketAddr::from(([0, 0, 0, 0], 0))],
+            Vec::new(),
+            false,
+        )
+        .await;
+        eprintln!("restart: the engine offered {:?}", offered.lock().unwrap());
 
         // Any bytes the VP9 packetizer turns into one access unit.
         let frame: Vec<u8> = (0..200u32).map(|i| (i % 251) as u8).collect();
@@ -1886,6 +1993,65 @@ pub(crate) mod tests {
         let _ = client.close().await;
     }
 
+    /// A phone whose only direct way here is IPv6, such as one on a carrier that
+    /// hands it a global IPv6 address, still gets the picture: the engine offers
+    /// its IPv6 addresses, never a loopback or link-local one, and a client that
+    /// can only send from `::1` connects and receives media.
+    #[tokio::test]
+    async fn a_client_with_only_an_ipv6_route_gets_the_picture() {
+        if !udp_addrs().iter().any(std::net::SocketAddr::is_ipv6) {
+            eprintln!("ipv6: skipped, this computer has no IPv6 address a peer could reach");
+            return;
+        }
+        let Connected {
+            engine,
+            client,
+            arrivals,
+            offered,
+            ..
+        } = connected(
+            vec![std::net::SocketAddr::from((
+                std::net::Ipv6Addr::LOCALHOST,
+                0,
+            ))],
+            Vec::new(),
+            false,
+        )
+        .await;
+        let offered = offered.lock().unwrap().clone();
+        eprintln!("ipv6: the engine offered {offered:?}");
+        let ipv6: Vec<std::net::Ipv6Addr> = offered
+            .iter()
+            .filter_map(|candidate| candidate.split(' ').nth(4)?.parse().ok())
+            .collect();
+        assert!(!ipv6.is_empty(), "no IPv6 candidate was offered");
+        assert!(
+            !ipv6
+                .iter()
+                .any(|ip| ip.is_loopback() || ip.segments()[0] & 0xffc0 == 0xfe80),
+            "a loopback or link-local address reached the client: {ipv6:?}"
+        );
+
+        let frame: Vec<u8> = (0..200u32).map(|i| (i % 251) as u8).collect();
+        for _ in 0..50 {
+            engine
+                .send_frame(&frame, true, Instant::now())
+                .await
+                .expect("a frame is sent");
+            tokio::time::sleep(Duration::from_millis(5)).await;
+        }
+        tokio::time::sleep(Duration::from_millis(200)).await;
+        let received = arrivals.lock().unwrap().len();
+        eprintln!("ipv6: {received} of 50 frames arrived at a client on ::1");
+        assert!(
+            received >= 25,
+            "the picture did not arrive over IPv6: {received} packets"
+        );
+
+        engine.close().await;
+        let _ = client.close().await;
+    }
+
     #[tokio::test]
     async fn a_forwarded_client_is_offered_ice_over_tcp_on_the_loopback() {
         let offered = |loopback_tcp: bool| async move {
@@ -1926,4 +2092,110 @@ pub(crate) mod tests {
             "no one else is offered a port on the loopback"
         );
     }
+
+    /// A STUN responder bound on the wildcard that answers every Binding
+    /// request with the requester's own address, the way a real STUN server
+    /// would. Reach it at the address `primary_ip` names, not at its bind
+    /// address: the wildcard receives for every interface.
+    async fn stun_responder() -> std::net::SocketAddr {
+        use rtc::stun::message::Setter;
+        let socket = tokio::net::UdpSocket::bind("0.0.0.0:0")
+            .await
+            .expect("a socket");
+        let addr = socket.local_addr().expect("a bound port");
+        tokio::spawn(async move {
+            let mut buffer = vec![0u8; 1500];
+            while let Ok((size, peer)) = socket.recv_from(&mut buffer).await {
+                let mut request = rtc::stun::message::Message::new();
+                request.raw = buffer[..size].to_vec();
+                if request.decode().is_err() {
+                    continue;
+                }
+                let mut response = rtc::stun::message::Message::new();
+                response.set_type(rtc::stun::message::BINDING_SUCCESS);
+                response.transaction_id = request.transaction_id;
+                let mapped = rtc::stun::xoraddr::XorMappedAddress {
+                    ip: peer.ip(),
+                    port: peer.port(),
+                };
+                if mapped.add_to(&mut response).is_err() {
+                    continue;
+                }
+                response.write_header();
+                let _ = socket.send_to(&response.raw, peer).await;
+            }
+        });
+        addr
+    }
+
+    /// The interface address this machine sources its own traffic from — the
+    /// address a socket bound to this machine's interfaces can reach. The
+    /// peer binds one socket per non-loopback interface (loopback is skipped
+    /// when host candidates are gathered), and Windows' strong-host model
+    /// refuses to send an interface-bound datagram to 127.0.0.1, where the
+    /// Linux weak-host model allows it — so a loopback STUN fixture gathers
+    /// nothing on Windows. A real STUN server sits on the subnet, and the
+    /// fixture does the same. The probe is a connected UDP socket: the OS
+    /// resolves the route and its source address without sending a packet.
+    fn primary_ip() -> std::net::IpAddr {
+        let probe = std::net::UdpSocket::bind("0.0.0.0:0").and_then(|probe| {
+            probe.connect("192.0.2.1:9")?; // TEST-NET-1: connected UDP sends nothing
+            probe.local_addr()
+        });
+        match probe {
+            Ok(addr) if !addr.ip().is_unspecified() && !addr.ip().is_loopback() => addr.ip(),
+            _ => std::net::IpAddr::from([127, 0, 0, 1]),
+        }
+    }
+
+    /// One ice_servers entry listing two URLs must put both in front of the
+    /// peer connection: the first responder here never answers, so any
+    /// reflexive candidate can only have come from the second URL. The engine
+    /// used to forward only the first URL of each entry, which lost the rest.
+    #[tokio::test]
+    async fn the_second_url_of_an_ice_server_entry_gathers_a_reflexive_candidate() {
+        let ip = primary_ip();
+        // A server that never answers: bound, so its port cannot be reused,
+        // and silent, so it is as good as unreachable.
+        let silent = tokio::net::UdpSocket::bind("0.0.0.0:0")
+            .await
+            .expect("a socket");
+        let unreachable = silent.local_addr().expect("a port");
+        let answering = stun_responder().await;
+
+        let (events, mut events_rx) = tokio::sync::mpsc::unbounded_channel();
+        let (_peer, _offer) = VideoPeer::offer(
+            TransportOptions {
+                ice_servers: vec![(
+                    vec![
+                        format!("stun:{ip}:{}", unreachable.port()),
+                        format!("stun:{ip}:{}", answering.port()),
+                    ],
+                    None,
+                    None,
+                )],
+                loopback_tcp: false,
+                pace_bps: 20_000_000.0,
+            },
+            events,
+            VideoCodec::Vp9,
+        )
+        .await
+        .expect("a peer connection");
+
+        // Host candidates arrive without the network; the reflexive one needs
+        // the binding round trip through the second URL of the entry.
+        let deadline = tokio::time::Instant::now() + Duration::from_secs(10);
+        loop {
+            let event = tokio::time::timeout_at(deadline, events_rx.recv())
+                .await
+                .expect("no reflexive candidate was ever gathered")
+                .expect("the peer event stream ended");
+            if let PeerEvent::Candidate { candidate, .. } = event {
+                if candidate.contains(" typ srflx ") {
+                    break;
+                }
+            }
+        }
+    }
 }