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    /// Fold a later sighting of the same device into this one.
57    ///
58    /// A device says what it is over several packets — the advertisement
59    /// carries the services, the scan response often carries the name — and a
60    /// scan that keeps repeated devices reports each as it arrives. Deciding
61    /// from any one of them is deciding from a fragment; this accumulates
62    /// them. A name is kept once learned, and the advertisement is merged as
63    /// [`Advertisement::merge`] describes.
64    ///
65    /// The caller matches identifiers: this does not check that `newer` is
66    /// the same device.
67    pub fn merge(&mut self, newer: Candidate) {
68        if newer.name.is_some() {
69            self.name = newer.name;
70        }
71        self.advertisement.merge(newer.advertisement);
72    }
73
74    /// Bluetooth Classic Class of Device, when the scanner reported it.
75    #[cfg(feature = "classic")]
76    pub fn class_of_device(&self) -> Option<crate::classic::ClassOfDevice> {
77        self.advertisement.class_of_device
78    }
79}
80
81/// A live stream of matching devices, ending when the scan stops.
82pub struct Candidates {
83    /// The sightings, as they arrive. Bounded: a chooser that stops reading
84    /// loses the oldest rather than stalling the radio.
85    pub inner: crate::backlog::Receiver<Candidate>,
86}
87
88impl Stream for Candidates {
89    type Item = Candidate;
90    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Candidate>> {
91        Pin::new(&mut self.inner).poll_next(cx)
92    }
93}
94
95/// Decides which device `request_device` returns.
96///
97/// Return the chosen [`Candidate::id`], or `None` to refuse — which surfaces to
98/// the caller as `NotFoundError`, the same thing a browser reports when a user
99/// dismisses the picker.
100pub trait DeviceChooser: Send + Sync + 'static {
101    /// Pick a device, or `None` to cancel the request.
102    ///
103    /// Returns the chosen device's id. The stream ends when the scan does, so
104    /// a chooser that reads to the end has seen everything there was.
105    fn choose(&self, candidates: Candidates) -> BoxFuture<'static, Option<String>>;
106}
107
108/// Take the first device that matches.
109///
110/// The default. Convenient and fully automatic — and worth being deliberate
111/// about, because it removes the consent step the Web Bluetooth security model
112/// is built on. Prefer a chooser that involves the operator for anything
113/// user-facing.
114#[derive(Debug, Clone)]
115pub struct FirstMatch {
116    timeout: Option<Duration>,
117}
118
119impl FirstMatch {
120    /// Wait indefinitely for a match.
121    pub fn new() -> Self {
122        Self { timeout: None }
123    }
124
125    /// Give up after `timeout` with `NotFoundError`.
126    pub fn with_timeout(timeout: Duration) -> Self {
127        Self {
128            timeout: Some(timeout),
129        }
130    }
131}
132
133impl Default for FirstMatch {
134    fn default() -> Self {
135        Self::with_timeout(Duration::from_secs(10))
136    }
137}
138
139impl DeviceChooser for FirstMatch {
140    fn choose(&self, mut candidates: Candidates) -> BoxFuture<'static, Option<String>> {
141        let timeout = self.timeout;
142        Box::pin(async move {
143            let first = async move { candidates.next().await.map(|c| c.id) };
144            match timeout {
145                None => first.await,
146                Some(d) => timer::timeout(d, first).await.ok().flatten(),
147            }
148        })
149    }
150}
151
152/// Collect for a window, then take the strongest signal.
153///
154/// Useful when several identical devices are in range and the nearest one is
155/// meant — a rack of sensors, say. Costs the full window in latency even if the
156/// right device answers immediately.
157#[derive(Debug, Clone)]
158pub struct StrongestSignal {
159    window: Duration,
160}
161
162impl StrongestSignal {
163    /// Collect for `window`, then take the strongest signal seen.
164    pub fn new(window: Duration) -> Self {
165        Self { window }
166    }
167}
168
169impl Default for StrongestSignal {
170    fn default() -> Self {
171        Self::new(Duration::from_secs(4))
172    }
173}
174
175impl DeviceChooser for StrongestSignal {
176    fn choose(&self, candidates: Candidates) -> BoxFuture<'static, Option<String>> {
177        let window = self.window;
178        Box::pin(async move {
179            let seen = collect_for(candidates, window).await;
180            seen.into_iter()
181                .max_by_key(|c| c.rssi().unwrap_or(i32::MIN))
182                .map(|c| c.id)
183        })
184    }
185}
186
187/// Run a closure over each candidate; the first `true` wins.
188///
189/// The escape hatch for application-specific logic that does not warrant its
190/// own type — matching a serial number out of the manufacturer data, say.
191pub struct Predicate<F>(std::sync::Arc<F>);
192
193impl<F> Predicate<F>
194where
195    F: Fn(&Candidate) -> bool + Send + Sync + 'static,
196{
197    /// Take the first candidate the predicate accepts.
198    pub fn new(predicate: F) -> Self {
199        Self(std::sync::Arc::new(predicate))
200    }
201}
202
203impl<F> DeviceChooser for Predicate<F>
204where
205    F: Fn(&Candidate) -> bool + Send + Sync + 'static,
206{
207    fn choose(&self, mut candidates: Candidates) -> BoxFuture<'static, Option<String>> {
208        let predicate = self.0.clone();
209        Box::pin(async move {
210            while let Some(c) = candidates.next().await {
211                if predicate(&c) {
212                    return Some(c.id);
213                }
214            }
215            None
216        })
217    }
218}
219
220/// Gather every candidate seen during `window`, deduplicated by id, keeping the
221/// most recent advertisement for each.
222async fn collect_for(mut candidates: Candidates, window: Duration) -> Vec<Candidate> {
223    let mut seen: HashMap<String, Candidate> = HashMap::new();
224    let gather = async {
225        while let Some(c) = candidates.next().await {
226            seen.insert(c.id.clone(), c);
227        }
228    };
229    let _ = timer::timeout(window, gather).await;
230    seen.into_values().collect()
231}
232
233/// A numbered list on stdout and a line read from stdin.
234///
235/// The closest thing a terminal program has to the browser's picker, and the
236/// only built-in chooser that preserves the consent step. Behind the
237/// `terminal-chooser` feature.
238#[cfg(feature = "terminal-chooser")]
239#[derive(Debug, Clone)]
240pub struct TerminalChooser {
241    window: Duration,
242    prompt: String,
243}
244
245#[cfg(feature = "terminal-chooser")]
246impl TerminalChooser {
247    /// Scan for `window`, then prompt.
248    pub fn new(window: Duration) -> Self {
249        Self {
250            window,
251            prompt: "Select a device".into(),
252        }
253    }
254
255    /// Replace the prompt text.
256    pub fn prompt(mut self, prompt: impl Into<String>) -> Self {
257        self.prompt = prompt.into();
258        self
259    }
260}
261
262#[cfg(feature = "terminal-chooser")]
263impl Default for TerminalChooser {
264    fn default() -> Self {
265        Self::new(Duration::from_secs(5))
266    }
267}
268
269#[cfg(feature = "terminal-chooser")]
270impl DeviceChooser for TerminalChooser {
271    fn choose(&self, candidates: Candidates) -> BoxFuture<'static, Option<String>> {
272        use std::io::Write;
273        let (window, prompt) = (self.window, self.prompt.clone());
274        Box::pin(async move {
275            eprintln!("Scanning for {:.0}s…", window.as_secs_f32());
276            let mut found = collect_for(candidates, window).await;
277            if found.is_empty() {
278                eprintln!("No matching devices found.");
279                return None;
280            }
281            found.sort_by_key(|c| std::cmp::Reverse(c.rssi().unwrap_or(i32::MIN)));
282
283            eprintln!();
284            for (i, c) in found.iter().enumerate() {
285                match c.rssi() {
286                    Some(db) => {
287                        eprintln!("  [{}] {:<28} {:>4} dBm  {}", i + 1, c.label(), db, c.id)
288                    }
289                    None => eprintln!("  [{}] {:<28} {:>8}  {}", i + 1, c.label(), "—", c.id),
290                }
291            }
292            eprint!("\n{prompt} [1-{}, or Enter to cancel]: ", found.len());
293            let _ = std::io::stderr().flush();
294
295            // stdin is blocking; read it off the executor.
296            let (tx, rx) = futures_channel::oneshot::channel();
297            std::thread::spawn(move || {
298                let mut line = String::new();
299                let ok = std::io::stdin().read_line(&mut line).is_ok();
300                let _ = tx.send(ok.then_some(line));
301            });
302            let line = rx.await.ok().flatten()?;
303
304            let n: usize = line.trim().parse().ok()?;
305            found.get(n.checked_sub(1)?).map(|c| c.id.clone())
306        })
307    }
308}
309
310#[cfg(test)]
311mod tests {
312    use super::*;
313
314    /// A name learned from a scan response must survive the next bare
315    /// advertisement, and the services from the advertisement must survive
316    /// the scan response.
317    #[test]
318    fn merging_sightings_accumulates_what_each_packet_said() {
319        let service = crate::uuid::BluetoothUuid::from_u16(0x180f);
320        let mut seen = Candidate {
321            id: "device".into(),
322            name: None,
323            advertisement: Advertisement {
324                service_uuids: vec![service],
325                ..Advertisement::default()
326            },
327        };
328        seen.merge(Candidate {
329            id: "device".into(),
330            name: Some("Named".into()),
331            advertisement: Advertisement::default(),
332        });
333        seen.merge(Candidate {
334            id: "device".into(),
335            name: None,
336            advertisement: Advertisement::default(),
337        });
338
339        assert_eq!(seen.name.as_deref(), Some("Named"));
340        assert_eq!(seen.advertisement.service_uuids, vec![service]);
341    }
342}