@desklink/host 0.5.4 → 0.5.7

package/engine/vendor/rtc-ice/src/agent/agent_test.rs

@@ -2930,6 +2930,212 @@ fn test_handle_inbound_request_defers_failing_connectivity_check() -> Result<()>
     Ok(())
 }
 
+// Regression test for the desklink patch that nominates off the check pass
+// (shape 2 in DESKLINK-PATCH.md) instead of the `check_interval` tick.
+//
+// Nomination is decided in `contact_candidates`, which the driver reaches on a
+// `check_interval` tick or when an inbound Binding request arrives while a valid pair
+// already exists. A peer that runs no checks of its own leaves the second path empty, so
+// a pair that becomes valid just after a tick waited a whole tick for its
+// USE-CANDIDATE: measured at 197 ms in the routed roam leg, the entire engine-side cost
+// between the pair becoming valid and the nomination leaving. The pass that nominates has
+// to be the one the validating response asked for.
+//
+// The agent's clock is driven by hand here and never reaches a tick, so the only thing
+// that can produce the nomination is the response itself.
+#[test]
+fn test_nominates_on_the_response_that_validates_the_pair() -> Result<()> {
+    use sansio::Protocol as _;
+
+    let base = Instant::now();
+    let mut a = Agent::new(
+        base,
+        Arc::new(AgentConfig {
+            is_controlling: true,
+            ..Default::default()
+        }),
+        test_crypto_provider(),
+    )?;
+
+    let local = CandidateHostConfig {
+        base_config: CandidateConfig {
+            network: "udp".to_owned(),
+            address: "192.168.0.2".to_owned(),
+            port: 777,
+            component: 1,
+            ..Default::default()
+        },
+        ..Default::default()
+    }
+    .new_candidate_host()?;
+    a.add_local_candidate(local)?;
+
+    let remote = CandidateHostConfig {
+        base_config: CandidateConfig {
+            network: "udp".to_owned(),
+            address: "172.17.0.3".to_owned(),
+            port: 999,
+            component: 1,
+            ..Default::default()
+        },
+        ..Default::default()
+    }
+    .new_candidate_host()?;
+    let remote_addr = remote.addr();
+    a.add_remote_candidate(remote)?;
+    assert_eq!(a.candidate_pairs.len(), 1, "one pair to check");
+
+    a.start_connectivity_checks(base, true, "remoteUfrag".to_owned(), "remotePwd".to_owned())?;
+
+    // The first pass pings the pair. Nothing has validated it yet, so nothing is
+    // nominated and no USE-CANDIDATE leaves.
+    a.handle_timeout(base)?;
+    let mut check = Message {
+        raw: a
+            .poll_write()
+            .expect("the agent checks the pair")
+            .message
+            .to_vec(),
+        ..Default::default()
+    };
+    check.decode()?;
+    assert_eq!(check.typ, MessageType::new(METHOD_BINDING, CLASS_REQUEST));
+    assert!(
+        !check.contains(ATTR_USE_CANDIDATE),
+        "a check that has not been answered must not nominate"
+    );
+    assert!(a.nominated_pair.is_none());
+
+    // The peer answers that check. Nothing else arrives: no inbound request (the test
+    // delivers no such message) and no tick (the clock moves by a millisecond).
+    let now = base + Duration::from_millis(1);
+    let mut response = Message::new();
+    response.build(&[
+        Box::new(check.clone()),
+        Box::new(BINDING_SUCCESS),
+        Box::new(XorMappedAddress {
+            ip: remote_addr.ip(),
+            port: remote_addr.port(),
+        }),
+        Box::new(MessageIntegrity::new_short_term_integrity_with_provider(
+            "remotePwd".to_owned(),
+            test_crypto_provider().crypto(),
+        )),
+        Box::new(FINGERPRINT),
+    ])?;
+    a.handle_inbound(now, &mut response, 0, remote_addr)?;
+    assert_eq!(
+        a.candidate_pairs[0].state,
+        CandidatePairState::Succeeded,
+        "the response validates the pair"
+    );
+
+    // The pair is valid, so the pass that nominates it is due now. Before the patch the
+    // deadline here was the next tick, a whole `check_interval` away.
+    let deadline = a
+        .poll_timeout()
+        .expect("a validated pair asks for a check pass");
+    assert!(
+        deadline <= now,
+        "the validating response must ask for a pass now, not at the next tick: deadline {deadline:?}, now {now:?}"
+    );
+
+    a.handle_timeout(now)?;
+    assert!(
+        a.nominated_pair.is_some(),
+        "the valid pair must be nominated on the pass the response asked for"
+    );
+    let mut nomination = Message {
+        raw: a
+            .poll_write()
+            .expect("the nomination leaves")
+            .message
+            .to_vec(),
+        ..Default::default()
+    };
+    nomination.decode()?;
+    assert!(
+        nomination.contains(ATTR_USE_CANDIDATE),
+        "the nomination is a Binding request carrying USE-CANDIDATE"
+    );
+
+    a.close()?;
+    Ok(())
+}
+
+// A peer that never answers a check must still retire the pair on the configured budget,
+// and the shape-2 patch must not change that budget: it only ever asks for a pass when a
+// response made a pair valid, so a silent peer never earns one. The agent's clock is driven
+// by hand, so this pins the pass count exactly instead of waiting for it.
+#[test]
+fn test_a_silent_peer_retires_the_pair_on_the_check_budget() -> Result<()> {
+    use sansio::Protocol as _;
+
+    let base = Instant::now();
+    let mut a = Agent::new(
+        base,
+        Arc::new(AgentConfig {
+            is_controlling: true,
+            ..Default::default()
+        }),
+        test_crypto_provider(),
+    )?;
+
+    let local = CandidateHostConfig {
+        base_config: CandidateConfig {
+            network: "udp".to_owned(),
+            address: "192.168.0.2".to_owned(),
+            port: 777,
+            component: 1,
+            ..Default::default()
+        },
+        ..Default::default()
+    }
+    .new_candidate_host()?;
+    a.add_local_candidate(local)?;
+
+    let remote = CandidateHostConfig {
+        base_config: CandidateConfig {
+            network: "udp".to_owned(),
+            address: "172.17.0.3".to_owned(),
+            port: 999,
+            component: 1,
+            ..Default::default()
+        },
+        ..Default::default()
+    }
+    .new_candidate_host()?;
+    a.add_remote_candidate(remote)?;
+    a.start_connectivity_checks(base, true, "remoteUfrag".to_owned(), "remotePwd".to_owned())?;
+
+    // `ping_all_candidates` retires a pair once `binding_request_count` passes
+    // `max_binding_requests`, so the first pass that retires it is one after the last
+    // request it sends: `max_binding_requests + 2` passes from checking.
+    let last_sending_pass = usize::from(DEFAULT_MAX_BINDING_REQUESTS) + 1;
+    let retiring_pass = last_sending_pass + 1;
+    let mut now = base;
+    for pass in 1..=retiring_pass {
+        now += Duration::from_millis(200);
+        a.handle_timeout(now)?;
+        while a.poll_write().is_some() {}
+        let deadline = a.poll_timeout().expect("the agent stays on its timers");
+        assert!(
+            deadline > now,
+            "pass {pass}: an unanswered peer must not ask for an extra pass (deadline {deadline:?}, now {now:?})"
+        );
+        let failed = a.candidate_pairs[0].state == CandidatePairState::Failed;
+        assert_eq!(
+            failed,
+            pass >= retiring_pass,
+            "pass {pass}: pair must retire on the budget, not before or after"
+        );
+    }
+    assert_eq!(a.connection_state, ConnectionState::Checking);
+
+    a.close()?;
+    Ok(())
+}
+
 // Safari (and Chrome) expose ICE host candidates behind an mDNS "<uuid>.local"
 // hostname by default. A QueryOnly agent (the default) must RESOLVE such a
 // candidate -- i.e. issue an mDNS query, which surfaces as an outbound packet to

package/engine/vendor/rtc-ice/src/agent/mod.rs

@@ -38,6 +38,9 @@ use stun::xoraddr::*;
 
 use crate::candidate::candidate_peer_reflexive::CandidatePeerReflexiveConfig;
 use crate::candidate::{candidate_pair::*, *};
+// desklink scout trace (dl-roam-postnom-attr):
+use crate::dl_trace;
+use crate::dl_trace::dl_ice;
 use crate::mdns::{MulticastDnsMode, create_multicast_dns, generate_multicast_dns_name};
 use crate::network_type::NetworkType;
 use crate::rand::*;
@@ -520,6 +523,17 @@ impl Agent {
                     }
                 }
 
+                // desklink scout trace: a remote candidate landed and an
+                // immediate check pass was requested for it.
+                if dl_trace::enabled() {
+                    dl_ice!(
+                        "{} remote_candidate_added {} pairs={} force_check",
+                        self.get_name(),
+                        self.remote_candidates[remote_index].addr(),
+                        self.candidate_pairs.len(),
+                    );
+                }
+
                 self.request_connectivity_check();
             }
         }
@@ -724,6 +738,18 @@ impl Agent {
     /// pair, and restarts the agent's timers. With nothing staged, the current credentials are
     /// kept and only the session is restarted.
     pub fn apply_restart(&mut self, now: Instant, keep_local_candidates: bool) -> Result<()> {
+        // desklink scout trace: restart applied — the new generation begins.
+        if dl_trace::enabled() {
+            dl_ice!(
+                "{} APPLY_RESTART keep_local={keep_local_candidates} role={} state={:?} local_cands={} remote_cands={} pairs={}",
+                self.get_name(),
+                if self.is_controlling { "controlling" } else { "controlled" },
+                self.connection_state,
+                self.local_candidates.len(),
+                self.remote_candidates.len(),
+                self.candidate_pairs.len(),
+            );
+        }
         // desklink patch: remember the pair media is on before the teardown
         // below clears it, so the ICE transport keeps sending and receiving on
         // it until the restarted generation nominates a pair (see
@@ -784,6 +810,20 @@ impl Agent {
     }
 
     fn contact(&mut self, now: Instant) {
+        // desklink scout trace: one line per agent contact() pass, so the tick
+        // cadence (and any forced pass) is measurable.
+        if dl_trace::enabled() {
+            dl_ice!(
+                "{} tick_begin state={:?} sel={:?} nom={:?} pairs={} outstanding={} force={}",
+                self.get_name(),
+                self.connection_state,
+                self.selected_pair,
+                self.nominated_pair,
+                self.candidate_pairs.len(),
+                self.pending_binding_requests.len(),
+                self.force_candidate_contact,
+            );
+        }
         // Consume any pending deferred-check request now that we are running one.
         // Reset before the early returns below so a failed/settled agent does not
         // keep asking `poll_timeout` for an immediate wake-up.
@@ -826,6 +866,19 @@ impl Agent {
         new_state: ConnectionState,
     ) {
         if self.connection_state != new_state {
+            // desklink scout trace: every connection-state transition, with the
+            // selection context that explains it.
+            if dl_trace::enabled() {
+                dl_ice!(
+                    "{} state {:?} -> {:?} sel={:?} nom={:?} pairs={}",
+                    self.get_name(),
+                    self.connection_state,
+                    new_state,
+                    self.selected_pair,
+                    self.nominated_pair,
+                    self.candidate_pairs.len(),
+                );
+            }
             // Connection has gone to failed, release all gathered candidates
             if new_state == ConnectionState::Failed {
                 self.set_selected_pair(now, None);
@@ -861,6 +914,19 @@ impl Agent {
                 self.candidate_pairs[pair_index]
             );
 
+            // desklink scout trace: nomination landed on a pair — the moment the
+            // agent moves to Connected.
+            if dl_trace::enabled() {
+                let p = &self.candidate_pairs[pair_index];
+                dl_ice!(
+                    "{} SELECTED_PAIR local={} remote={} pairs={}",
+                    self.get_name(),
+                    self.local_candidates[p.local_index].addr(),
+                    self.remote_candidates[p.remote_index].addr(),
+                    self.candidate_pairs.len(),
+                );
+            }
+
             self.candidate_pairs[pair_index].nominated = true;
             self.selected_pair = Some(pair_index);
             // desklink patch: the restarted generation now has a nominated pair,
@@ -1101,6 +1167,20 @@ impl Agent {
             self.remote_candidates[remote_index],
         );
 
+        // desklink scout trace: every outbound connectivity check / nomination,
+        // with the transaction id, so the relay's wire log can be matched to it.
+        if dl_trace::enabled() {
+            dl_ice!(
+                "{} SEND_REQUEST txn={:?} use_candidate={} local={} remote={} outstanding={}",
+                self.get_name(),
+                m.transaction_id,
+                m.contains(ATTR_USE_CANDIDATE),
+                self.local_candidates[local_index].addr(),
+                self.remote_candidates[remote_index].addr(),
+                self.pending_binding_requests.len(),
+            );
+        }
+
         self.invalidate_pending_binding_requests(now);
 
         self.pending_binding_requests.push(BindingRequest {
@@ -1125,6 +1205,17 @@ impl Agent {
         local_index: usize,
         remote_index: usize,
     ) {
+        // desklink scout trace: the answer to an inbound connectivity check, and
+        // whether the request it answered carried the nomination.
+        if dl_trace::enabled() {
+            dl_ice!(
+                "{} SEND_SUCCESS role={} txn={:?} use_candidate={}",
+                self.get_name(),
+                if self.is_controlling { "controlling" } else { "controlled" },
+                m.transaction_id,
+                m.contains(ATTR_USE_CANDIDATE),
+            );
+        }
         let addr = self.remote_candidates[remote_index].addr();
         let (ip, port) = (addr.ip(), addr.port());
         let local_pwd = self.ufrag_pwd.local_credentials.pwd.clone();

package/engine/vendor/rtc-ice/src/dl_trace.rs

@@ -0,0 +1,49 @@
+//! desklink scout instrumentation (dev-only, `DESKLINK_ICE_TRACE=1`).
+//!
+//! Timestamped stderr trace of the ICE agent's restart/check/nomination timeline
+//! for task dl-roam-postnom-attr. Not part of the shipped patch; see
+//! DESKLINK-PATCH.md. Every call site is marked `// desklink scout trace:` so the
+//! whole diff is trivially droppable.
+
+use std::fmt::Arguments;
+use std::sync::OnceLock;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// Whether tracing is on; cached, so the hot path is one atomic load.
+pub(crate) fn enabled() -> bool {
+    static ON: OnceLock<bool> = OnceLock::new();
+    *ON.get_or_init(|| flag("DESKLINK_ICE_TRACE"))
+}
+
+/// A dev-only scout switch, read fresh each time (these are experiments).
+pub(crate) fn flag(name: &str) -> bool {
+    match std::env::var(name) {
+        Ok(v) => v != "0" && !v.is_empty(),
+        Err(_) => false,
+    }
+}
+
+/// Microseconds since the Unix epoch; the vendored crate, the engine and the
+/// browser/relay side all stamp this way (ms on the JS side), so lines from
+/// every observer sort into one timeline.
+pub(crate) fn t_us() -> u128 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_micros())
+        .unwrap_or(0)
+}
+
+/// Emit one trace line.
+pub(crate) fn write(line: Arguments<'_>) {
+    eprintln!("[ice {}] {}", t_us(), line);
+}
+
+macro_rules! dl_ice {
+    ($($arg:tt)*) => {{
+        if $crate::dl_trace::enabled() {
+            $crate::dl_trace::write(format_args!($($arg)*));
+        }
+    }};
+}
+
+pub(crate) use dl_ice;

package/engine/vendor/rtc-ice/src/lib.rs

@@ -58,6 +58,9 @@
 /// without adding — and version-matching — a direct `rtc-crypto` dependency.
 pub use crypto;
 
+// desklink scout trace: dev-only ICE timeline instrumentation (dl-roam-postnom-attr).
+pub(crate) mod dl_trace;
+
 pub mod agent;
 /// The ICE-specific STUN attributes carried in connectivity checks.
 pub mod attributes;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@desklink/host",
-    "version": "0.5.4",
+    "version": "0.5.7",
     "license": "Apache-2.0",
     "repository": {
         "type": "git",
@@ -38,7 +38,7 @@
         "ws": "8.21.3"
     },
     "optionalDependencies": {
-        "@desklink/host-linux-x64-gnu": "0.5.4",
-        "@desklink/host-darwin-arm64": "0.5.4"
+        "@desklink/host-linux-x64-gnu": "0.5.7",
+        "@desklink/host-darwin-arm64": "0.5.7"
     }
 }