Skip to main content

webbluetooth_core/
chooser.rs

1//! Choosing a device — the part a browser draws a dialog for.
2//!
3//! `requestDevice()` is defined around a user gesture and a chooser UI: the
4//! page proposes filters, the *browser* scans, and a human picks one device.
5//! That consent step is the whole reason the API is safe to expose, so it is
6//! kept here as a real extension point rather than quietly dropped. A library
7//! has no chrome to draw, so the decision is a trait: implement it against
8//! whatever UI the application has, or use one of the built-ins.
9//!
10//! The candidate stream may report the same device more than once — every
11//! advertisement is forwarded, so RSSI keeps updating while a chooser
12//! deliberates. Choosers that present a list should deduplicate by
13//! [`Candidate::id`].
14
15use crate::filter::Advertisement;
16use crate::timer;
17use futures_core::Stream;
18// Re-exported rather than merely imported: `DeviceChooser::choose` returns
19// one, so implementing the trait means naming the type — and without this,
20// that meant adding `futures-util` to your own Cargo.toml to implement a trait
21// from this one. Both of this crate's chooser examples had to. It is the same
22// gap the prelude was built to close for `StreamExt`, left open one level
23// down.
24pub use futures_util::future::BoxFuture;
25use futures_util::StreamExt;
26use std::collections::HashMap;
27use std::pin::Pin;
28use std::task::{Context, Poll};
29use std::time::Duration;
30
31/// A device seen during a scan that matched the request's filters.
32#[derive(Debug, Clone)]
33pub struct Candidate {
34    /// The per-host identifier — `BluetoothDevice.id`. Stable for this machine
35    /// and this peripheral; not the Bluetooth address, which Apple never
36    /// exposes.
37    pub id: String,
38    /// The device's name, from the GAP name or the advertised local name.
39    pub name: Option<String>,
40    /// The advertisement that matched.
41    pub advertisement: Advertisement,
42}
43
44impl Candidate {
45    /// Signal strength in dBm, or `None` if the radio did not report one.
46    pub fn rssi(&self) -> Option<i32> {
47        (self.advertisement.rssi != crate::filter::UNAVAILABLE_RSSI)
48            .then_some(self.advertisement.rssi)
49    }
50
51    /// Something printable: the name if there is one, else the identifier.
52    pub fn label(&self) -> &str {
53        self.name.as_deref().unwrap_or(&self.id)
54    }
55}
56
57/// A live stream of matching devices, ending when the scan stops.
58pub struct Candidates {
59    /// The sightings, as they arrive. Bounded: a chooser that stops reading
60    /// loses the oldest rather than stalling the radio.
61    pub inner: crate::backlog::Receiver<Candidate>,
62}
63
64impl Stream for Candidates {
65    type Item = Candidate;
66    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Candidate>> {
67        Pin::new(&mut self.inner).poll_next(cx)
68    }
69}
70
71/// Decides which device `request_device` returns.
72///
73/// Return the chosen [`Candidate::id`], or `None` to refuse — which surfaces to
74/// the caller as `NotFoundError`, the same thing a browser reports when a user
75/// dismisses the picker.
76pub trait DeviceChooser: Send + Sync + 'static {
77    /// Pick a device, or `None` to cancel the request.
78    ///
79    /// Returns the chosen device's id. The stream ends when the scan does, so
80    /// a chooser that reads to the end has seen everything there was.
81    fn choose(&self, candidates: Candidates) -> BoxFuture<'static, Option<String>>;
82}
83
84/// Take the first device that matches.
85///
86/// The default. Convenient and fully automatic — and worth being deliberate
87/// about, because it removes the consent step the Web Bluetooth security model
88/// is built on. Prefer a chooser that involves the operator for anything
89/// user-facing.
90#[derive(Debug, Clone)]
91pub struct FirstMatch {
92    timeout: Option<Duration>,
93}
94
95impl FirstMatch {
96    /// Wait indefinitely for a match.
97    pub fn new() -> Self {
98        Self { timeout: None }
99    }
100
101    /// Give up after `timeout` with `NotFoundError`.
102    pub fn with_timeout(timeout: Duration) -> Self {
103        Self {
104            timeout: Some(timeout),
105        }
106    }
107}
108
109impl Default for FirstMatch {
110    fn default() -> Self {
111        Self::with_timeout(Duration::from_secs(10))
112    }
113}
114
115impl DeviceChooser for FirstMatch {
116    fn choose(&self, mut candidates: Candidates) -> BoxFuture<'static, Option<String>> {
117        let timeout = self.timeout;
118        Box::pin(async move {
119            let first = async move { candidates.next().await.map(|c| c.id) };
120            match timeout {
121                None => first.await,
122                Some(d) => timer::timeout(d, first).await.ok().flatten(),
123            }
124        })
125    }
126}
127
128/// Collect for a window, then take the strongest signal.
129///
130/// Useful when several identical devices are in range and the nearest one is
131/// meant — a rack of sensors, say. Costs the full window in latency even if the
132/// right device answers immediately.
133#[derive(Debug, Clone)]
134pub struct StrongestSignal {
135    window: Duration,
136}
137
138impl StrongestSignal {
139    /// Collect for `window`, then take the strongest signal seen.
140    pub fn new(window: Duration) -> Self {
141        Self { window }
142    }
143}
144
145impl Default for StrongestSignal {
146    fn default() -> Self {
147        Self::new(Duration::from_secs(4))
148    }
149}
150
151impl DeviceChooser for StrongestSignal {
152    fn choose(&self, candidates: Candidates) -> BoxFuture<'static, Option<String>> {
153        let window = self.window;
154        Box::pin(async move {
155            let seen = collect_for(candidates, window).await;
156            seen.into_iter()
157                .max_by_key(|c| c.rssi().unwrap_or(i32::MIN))
158                .map(|c| c.id)
159        })
160    }
161}
162
163/// Run a closure over each candidate; the first `true` wins.
164///
165/// The escape hatch for application-specific logic that does not warrant its
166/// own type — matching a serial number out of the manufacturer data, say.
167pub struct Predicate<F>(std::sync::Arc<F>);
168
169impl<F> Predicate<F>
170where
171    F: Fn(&Candidate) -> bool + Send + Sync + 'static,
172{
173    /// Take the first candidate the predicate accepts.
174    pub fn new(predicate: F) -> Self {
175        Self(std::sync::Arc::new(predicate))
176    }
177}
178
179impl<F> DeviceChooser for Predicate<F>
180where
181    F: Fn(&Candidate) -> bool + Send + Sync + 'static,
182{
183    fn choose(&self, mut candidates: Candidates) -> BoxFuture<'static, Option<String>> {
184        let predicate = self.0.clone();
185        Box::pin(async move {
186            while let Some(c) = candidates.next().await {
187                if predicate(&c) {
188                    return Some(c.id);
189                }
190            }
191            None
192        })
193    }
194}
195
196/// Gather every candidate seen during `window`, deduplicated by id, keeping the
197/// most recent advertisement for each.
198async fn collect_for(mut candidates: Candidates, window: Duration) -> Vec<Candidate> {
199    let mut seen: HashMap<String, Candidate> = HashMap::new();
200    let gather = async {
201        while let Some(c) = candidates.next().await {
202            seen.insert(c.id.clone(), c);
203        }
204    };
205    let _ = timer::timeout(window, gather).await;
206    seen.into_values().collect()
207}
208
209/// A numbered list on stdout and a line read from stdin.
210///
211/// The closest thing a terminal program has to the browser's picker, and the
212/// only built-in chooser that preserves the consent step. Behind the
213/// `terminal-chooser` feature.
214#[cfg(feature = "terminal-chooser")]
215#[derive(Debug, Clone)]
216pub struct TerminalChooser {
217    window: Duration,
218    prompt: String,
219}
220
221#[cfg(feature = "terminal-chooser")]
222impl TerminalChooser {
223    /// Scan for `window`, then prompt.
224    pub fn new(window: Duration) -> Self {
225        Self {
226            window,
227            prompt: "Select a device".into(),
228        }
229    }
230
231    /// Replace the prompt text.
232    pub fn prompt(mut self, prompt: impl Into<String>) -> Self {
233        self.prompt = prompt.into();
234        self
235    }
236}
237
238#[cfg(feature = "terminal-chooser")]
239impl Default for TerminalChooser {
240    fn default() -> Self {
241        Self::new(Duration::from_secs(5))
242    }
243}
244
245#[cfg(feature = "terminal-chooser")]
246impl DeviceChooser for TerminalChooser {
247    fn choose(&self, candidates: Candidates) -> BoxFuture<'static, Option<String>> {
248        use std::io::Write;
249        let (window, prompt) = (self.window, self.prompt.clone());
250        Box::pin(async move {
251            eprintln!("Scanning for {:.0}s…", window.as_secs_f32());
252            let mut found = collect_for(candidates, window).await;
253            if found.is_empty() {
254                eprintln!("No matching devices found.");
255                return None;
256            }
257            found.sort_by_key(|c| std::cmp::Reverse(c.rssi().unwrap_or(i32::MIN)));
258
259            eprintln!();
260            for (i, c) in found.iter().enumerate() {
261                match c.rssi() {
262                    Some(db) => {
263                        eprintln!("  [{}] {:<28} {:>4} dBm  {}", i + 1, c.label(), db, c.id)
264                    }
265                    None => eprintln!("  [{}] {:<28} {:>8}  {}", i + 1, c.label(), "—", c.id),
266                }
267            }
268            eprint!("\n{prompt} [1-{}, or Enter to cancel]: ", found.len());
269            let _ = std::io::stderr().flush();
270
271            // stdin is blocking; read it off the executor.
272            let (tx, rx) = futures_channel::oneshot::channel();
273            std::thread::spawn(move || {
274                let mut line = String::new();
275                let ok = std::io::stdin().read_line(&mut line).is_ok();
276                let _ = tx.send(ok.then_some(line));
277            });
278            let line = rx.await.ok().flatten()?;
279
280            let n: usize = line.trim().parse().ok()?;
281            found.get(n.checked_sub(1)?).map(|c| c.id.clone())
282        })
283    }
284}