diff --git a/CHANGELOG.md b/CHANGELOG.md index a631c85..d5bcd59 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **`DeviceNotFoundReason::Ambiguous` and `DeviceNotFoundReason::NoExactMatch`**, returned for a name that two nearby devices share and for a partial name (see Changed) - **`Device::connect_with_scan_options`**, to choose how long a connect searches for the device +- **`aranet_core::peripheral_name`**, the name aranet uses for a device, read from btleplug's `PeripheralProperties`: the name the device advertises, or on macOS, for a device that hasn't advertised one, the name macOS has stored for it. A program that reads `local_name` itself should call it instead (see Changed) - **Optional data retention** — `[storage.retention] readings_days` and `history_days` make the service delete older rows at startup and then hourly, in small batches. Off by default. `history_days` also prunes the history cache that `aranet sync` fills, which the next sync may download again. Both limits apply to everything in the database, including readings that the `aranet` CLI, TUI and GUI stored there when they share it (the default, except under the systemd system service and Docker) - **Setting `security.api_key_enabled = true` without `security.api_key`** now generates a key and saves it to `server.toml` - **The API key is also accepted as `Authorization: Bearer `**, so Prometheus can scrape an authenticated service with `authorization: { type: Bearer, credentials: … }`. A repeated `X-API-Key` or `Authorization` header, or an `X-API-Key` that isn't plain text, is never read as a key, so a request that sends its key that way is refused @@ -30,6 +31,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **`ReconnectingDevice` retries** — it reconnects only after connection errors (not connected, timeouts, connection failures and Bluetooth link errors); other errors, such as a characteristic the device doesn't have, are returned at once. Operations that fail together share one reconnect; `cancel_reconnect()` and `disconnect()` stop a reconnect wait at once, and a reconnect already in progress no longer undoes `disconnect()`. A `with_device` closure can run a second time, but only after a connection error. `reconnect()`, and so `AranetDevice::connect()`, called while another reconnect is running waits for it instead of starting its own, and returns `Error::NotConnected` if that one gave up or `disconnect()` stopped it, or `Error::Cancelled` after `cancel_reconnect()`; operations waiting for a reconnect do the same. The old connection is closed when a reconnect starts, so while it runs, and after it fails, `ReconnectingDevice::name()` returns `None` and `address()` returns the identifier - **`DeviceManager`** — devices that were disconnected, evicted or removed stay that way until `connect()` is called; automatic reconnects back off per device using its `ReconnectOptions` and stop after `max_attempts` with one `DeviceEvent::Error`; `ManagerConfig::default().default_reconnect_options` is now `ReconnectOptions::unlimited()`; health checks run concurrently, a failed reconnect shortens the adaptive check interval even when other devices are healthy, and the monitor stops as soon as it is cancelled; a second `connect()` of a device waits for the first and returns its real result; a `connect()` that hasn't connected yet when `disconnect()`, `disconnect_all()`, `evict_lowest_priority()` or `remove_device()` is called for the same device returns `Error::Cancelled` and releases the sensor, instead of `Ok` or adding the device back; these four send `Disconnected`, and `remove_device()` removes the device, even when closing the connection fails or the call is cancelled, and still return a failed close's error; `max_concurrent_connections` counts connects in progress, so `connect_all` respects it; `connect()` on a device whose connection has dropped reconnects instead of returning `Ok`; `add_device`, `add_device_with_options` and `add_device_with_priority` reject invalid `ReconnectOptions`; passive readings from the hybrid monitor no longer reset a device's reconnect backoff - **`ConnectionConfig::discovery_timeout` on Linux** — while BlueZ is still discovering the services of a device it has just connected, a connect waits at least 20 s for it, even when `discovery_timeout` is shorter (`ConnectionConfig::fast()` sets 5 s) +- **`ConnectionConfig::discovery_timeout` on macOS** — by btleplug's source code, version 0.13 reports a macOS connection as made as soon as the link is up and discovers the services in a step of its own, so `discovery_timeout` (10 s by default, 8 s in the TUI) now limits that discovery, where the link and the discovery shared the connect timeout before; a connect has more time in all (25 s where it had 15 s by default, 40 s where it had 30 s in `aranet watch`, 18 s where it had 10 s in the TUI), and a discovery that alone takes longer than `discovery_timeout` fails with "Operation 'discover services' timed out". No `aranet` option or config key sets `discovery_timeout`: in a connect made by `aranet watch`, `--timeout` (or the `timeout` config key) now limits only the time the link takes to come up +- **Bluetooth errors on macOS** — by btleplug's source code, an error that macOS reports for a read, a write or a subscribe is now returned as a "Bluetooth error". In 0.2.1 a read or a write ran into its time limit and failed as a timeout. A read that needs pairing can still time out while macOS shows its pairing window +- **Two new failures on macOS** — by btleplug's source code, once macOS reports that a sensor's services changed, reads and writes of those services fail with "Service no longer available" until the next connect, and one that is in progress at that moment fails with "Service invalidated; rediscovery required"; and when the characteristics of a service can't be discovered, the connect still succeeds and reads then fail with "Characteristic not found", which `ReconnectingDevice` returns without reconnecting (`aranet watch` and the service connect again at their next poll) +- **Device names on macOS** — a sensor whose name stored by macOS differs from the name it advertises was listed as ` []`, for example `Kitchen [Aranet4 1A2B3]`. btleplug 0.13 no longer builds that form: the sensor is listed under its advertised name alone, `Aranet4 1A2B3`, and `-d Kitchen` or `-d "Kitchen [Aranet4 1A2B3]"` no longer finds it. Use the advertised name or the identifier that `aranet scan` prints. The rule for names on Linux and Windows is unchanged +- **Linux: Bluetooth adapters** — by btleplug's source code and that of its BlueZ library, bluez-async 0.9, adapters that BlueZ reports with a `bluetooth:` modalias are now listed, where only those with a `usb:` modalias were before. BlueZ (5.82, by its source code) gives every adapter of a host the same modalias, built from `DeviceID` in `/etc/bluetooth/main.conf` (`usb:…` unless that is changed), so this matters only on a host that sets `DeviceID = bluetooth:…`: there 0.2.1 found no adapter and failed with "no Bluetooth adapter available", and its adapters are now found. On every other host the adapters listed are the same as before +- **Breaking (library):** `aranet-core` now builds on btleplug 0.13 (0.13.5 or a later 0.13 release; 0.2.1 used 0.11) and so, on Linux, on bluez-async 0.9 (was 0.8). btleplug is a public dependency of `aranet-core` through `Error::Bluetooth`, `DiscoveredDevice::id`, `scan::get_adapter`, `scan::scan_with_adapter`, the `scan::find_device…` functions, `Device::connect_with_adapter`, `Device::from_peripheral…`, `format_peripheral_id`, `create_identifier` and the new `peripheral_name`, so a program that uses these with its own btleplug dependency must move to btleplug 0.13 too, and bumping it is a breaking change. `btleplug::Error`, which `Error::Bluetooth` carries, has a new variant, `NoAdapterAvailable`. Code that reads `PeripheralProperties::local_name` itself gets a different value on every platform: BlueZ's alias on Linux, the system's name for the device after a connect on Windows, and on macOS no longer the combined form (see "Device names on macOS"); `aranet_core::peripheral_name` returns the name aranet uses. On macOS, btleplug 0.13.5 logs `Shouldn't get anything but Ok!` at error level after every disconnect that macOS confirms, under the log target `btleplug::corebluetooth::peripheral`; the disconnect has succeeded, and the line can be ignored. `aranet`, `aranet-service` and the GUI leave that target out of their default log output: `aranet --verbose`, and a `RUST_LOG` of your own in `aranet` and the GUI, can still show the line, while `aranet-service` and `aranet server` keep the target off whatever `RUST_LOG` says. A program with its own logger must filter it out itself - **Breaking (library):** `aranet-service`'s Rust API changed for 0.3.0: - **`Collector::stop`** returns `CollectorStopResult`, and **`CollectorError`** is `#[non_exhaustive]` with a new `Timeout(Duration)` variant - **`PrometheusPusher::start`** returns `Option>` diff --git a/Cargo.lock b/Cargo.lock index d1ba71f..924dfca 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -151,7 +151,7 @@ dependencies = [ "android-properties", "bitflags 2.13.2", "cc", - "jni 0.22.4", + "jni", "libc", "log", "ndk", @@ -849,16 +849,16 @@ dependencies = [ [[package]] name = "bluez-async" -version = "0.8.2" +version = "0.9.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "84ae4213cc2a8dc663acecac67bbdad05142be4d8ef372b6903abf878b0c690a" +checksum = "23a32d8f6aedb42c4ec4ed4e39720ee0e807e72c93feb7cd6483f51d08ca1f65" dependencies = [ "bitflags 2.13.2", "bluez-generated", "dbus", "dbus-tokio", "futures", - "itertools", + "itertools 0.15.0", "log", "serde", "serde-xml-rs", @@ -878,30 +878,29 @@ dependencies = [ [[package]] name = "btleplug" -version = "0.11.8" +version = "0.13.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c9a11621cb2c8c024e444734292482b1ad86fb50ded066cf46252e46643c8748" +checksum = "3d836502de731602ea87cbb307065e8feaed4fd10f0855a75b0b87944ee011dc" dependencies = [ "async-trait", "bitflags 2.13.2", "bluez-async", - "dashmap 6.2.1", + "dashmap", "dbus", "futures", - "jni 0.19.0", - "jni-utils", + "jni", "log", - "objc2 0.5.2", + "objc2 0.6.4", "objc2-core-bluetooth", - "objc2-foundation 0.2.2", + "objc2-foundation 0.3.2", "once_cell", "static_assertions", "thiserror 2.0.21", "tokio", "tokio-stream", "uuid", - "windows 0.61.3", - "windows-future", + "windows 0.62.2", + "windows-future 0.3.2", ] [[package]] @@ -1051,12 +1050,6 @@ dependencies = [ "shlex", ] -[[package]] -name = "cesu8" -version = "1.1.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6d43a04d8753f35258c91f8ec639f792891f748a1edbd759cf1dcea3382ad83c" - [[package]] name = "cfg-expr" version = "0.15.8" @@ -1466,19 +1459,6 @@ dependencies = [ "syn 3.0.6", ] -[[package]] -name = "dashmap" -version = "5.5.3" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "978747c1d849a7d2ee5e8adc0159961c48fb7e5db2f06af6723b80123bb53856" -dependencies = [ - "cfg-if", - "hashbrown 0.14.5", - "lock_api", - "once_cell", - "parking_lot_core", -] - [[package]] name = "dashmap" version = "6.2.1" @@ -2559,7 +2539,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9efcab3c1958580ff1f25a2a41be1668f7603d849bb63af523b208a3cc1223b8" dependencies = [ "cfg-if", - "dashmap 6.2.1", + "dashmap", "futures-sink", "futures-timer", "futures-util", @@ -3110,24 +3090,19 @@ dependencies = [ ] [[package]] -name = "itoa" -version = "1.0.18" +name = "itertools" +version = "0.15.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" +checksum = "8b4baf93f58d4425749ca49a51c50ebab072c5df6994d08fed93541c331481dc" +dependencies = [ + "either", +] [[package]] -name = "jni" -version = "0.19.0" +name = "itoa" +version = "1.0.18" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c6df18c2e3db7e453d3c6ac5b3e9d5182664d28788126d39b91f2d1e22b017ec" -dependencies = [ - "cesu8", - "combine", - "jni-sys 0.3.1", - "log", - "thiserror 1.0.69", - "walkdir", -] +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" [[package]] name = "jni" @@ -3187,21 +3162,6 @@ dependencies = [ "syn 2.0.119", ] -[[package]] -name = "jni-utils" -version = "0.1.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "259e9f2c3ead61de911f147000660511f07ab00adeed1d84f5ac4d0386e7a6c4" -dependencies = [ - "dashmap 5.5.3", - "futures", - "jni 0.19.0", - "log", - "once_cell", - "static_assertions", - "uuid", -] - [[package]] name = "jobserver" version = "0.1.35" @@ -3909,13 +3869,13 @@ dependencies = [ [[package]] name = "objc2-core-bluetooth" -version = "0.2.2" +version = "0.3.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5a644b62ffb826a5277f536cf0f701493de420b13d40e700c452c36567771111" +checksum = "79b30b9eacc37434a61377866f68b27acef9fa5496f25cc9ca8b2549032e0394" dependencies = [ "bitflags 2.13.2", - "objc2 0.5.2", - "objc2-foundation 0.2.2", + "objc2 0.6.4", + "objc2-foundation 0.3.2", ] [[package]] @@ -4939,7 +4899,7 @@ dependencies = [ "compact_str", "critical-section", "hashbrown 0.17.1", - "itertools", + "itertools 0.14.0", "kasuari", "lru", "palette", @@ -5004,7 +4964,7 @@ dependencies = [ "hashbrown 0.17.1", "indoc", "instability", - "itertools", + "itertools 0.14.0", "line-clipping", "ratatui-core", "serde", @@ -6566,7 +6526,7 @@ version = "2.0.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "16b380a1238663e5f8a691f9039c73e1cdae598a30e9855f541d29b08b53e9a5" dependencies = [ - "itertools", + "itertools 0.14.0", "unicode-segmentation", "unicode-width", ] @@ -6929,7 +6889,7 @@ version = "1.2.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "62c35be770821a214dbc362fc26908c853e776c0004294d0b10b8a6bad582f94" dependencies = [ - "jni 0.22.4", + "jni", "log", "ndk-context", "objc2 0.6.4", @@ -7236,11 +7196,23 @@ version = "0.61.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9babd3a767a4c1aef6900409f85f5d53ce2544ccdfaa86dad48c91782c6d6893" dependencies = [ - "windows-collections", + "windows-collections 0.2.0", "windows-core 0.61.2", - "windows-future", + "windows-future 0.2.1", "windows-link 0.1.3", - "windows-numerics", + "windows-numerics 0.2.0", +] + +[[package]] +name = "windows" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580" +dependencies = [ + "windows-collections 0.3.2", + "windows-core 0.62.2", + "windows-future 0.3.2", + "windows-numerics 0.3.1", ] [[package]] @@ -7252,6 +7224,15 @@ dependencies = [ "windows-core 0.61.2", ] +[[package]] +name = "windows-collections" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610" +dependencies = [ + "windows-core 0.62.2", +] + [[package]] name = "windows-core" version = "0.58.0" @@ -7278,6 +7259,19 @@ dependencies = [ "windows-strings 0.4.2", ] +[[package]] +name = "windows-core" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb" +dependencies = [ + "windows-implement 0.60.2", + "windows-interface 0.59.3", + "windows-link 0.2.1", + "windows-result 0.4.1", + "windows-strings 0.5.1", +] + [[package]] name = "windows-future" version = "0.2.1" @@ -7286,7 +7280,18 @@ checksum = "fc6a41e98427b19fe4b73c550f060b59fa592d7d686537eebf9385621bfbad8e" dependencies = [ "windows-core 0.61.2", "windows-link 0.1.3", - "windows-threading", + "windows-threading 0.1.0", +] + +[[package]] +name = "windows-future" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb" +dependencies = [ + "windows-core 0.62.2", + "windows-link 0.2.1", + "windows-threading 0.2.1", ] [[package]] @@ -7355,6 +7360,16 @@ dependencies = [ "windows-link 0.1.3", ] +[[package]] +name = "windows-numerics" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26" +dependencies = [ + "windows-core 0.62.2", + "windows-link 0.2.1", +] + [[package]] name = "windows-result" version = "0.2.0" @@ -7373,6 +7388,15 @@ dependencies = [ "windows-link 0.1.3", ] +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link 0.2.1", +] + [[package]] name = "windows-strings" version = "0.1.0" @@ -7392,6 +7416,15 @@ dependencies = [ "windows-link 0.1.3", ] +[[package]] +name = "windows-strings" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091" +dependencies = [ + "windows-link 0.2.1", +] + [[package]] name = "windows-sys" version = "0.48.0" @@ -7494,6 +7527,15 @@ dependencies = [ "windows-link 0.1.3", ] +[[package]] +name = "windows-threading" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37" +dependencies = [ + "windows-link 0.2.1", +] + [[package]] name = "windows-version" version = "0.1.7" diff --git a/Cargo.toml b/Cargo.toml index b41c356..94a8dbe 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -31,7 +31,9 @@ aranet-service = { version = "0.2.1", path = "crates/aranet-service" } # workspace entry already does, so it is set here. aranet-cli = { version = "0.2.1", path = "crates/aranet-cli", default-features = false } -btleplug = "0.11" +# At least 0.13.5: the first release with the fixes for btleplug's issues #494 (macOS memory +# growth while scanning) and #496 (the 5 s BlueZ service-discovery wait). 0.13.0 is yanked. +btleplug = "0.13.5" tokio = { version = "1", features = ["full"] } thiserror = "2" bytes = "1" diff --git a/crates/aranet-cli/src/format.rs b/crates/aranet-cli/src/format.rs index f2fc519..204998c 100644 --- a/crates/aranet-cli/src/format.rs +++ b/crates/aranet-cli/src/format.rs @@ -1530,8 +1530,13 @@ mod tests { // ======================================================================== // Note: DiscoveredDevice tests only run on macOS because: - // - Linux: bluez-async's DeviceId/AdapterId constructors are private - // - Windows: btleplug's PeripheralId constructor is not publicly accessible + // - Linux: PeripheralId is made from a bluez_async::DeviceId (btleplug + // 0.13.5 `src/bluez/peripheral.rs:358`), and these tests can't name that + // type: btleplug doesn't re-export bluez-async, and aranet-cli doesn't + // depend on it directly + // - Windows: PeripheralId can be made from a btleplug::api::BDAddr + // (btleplug 0.13.5 `src/winrtble/peripheral.rs:732`), but no helper like + // `make_test_peripheral_id` has been written for it // The formatting logic is still tested on macOS where PeripheralId can be created from UUID. /// Create a test PeripheralId for macOS (uses UUID) diff --git a/crates/aranet-cli/src/gui/mod.rs b/crates/aranet-cli/src/gui/mod.rs index 273f1f3..ec6117c 100644 --- a/crates/aranet-cli/src/gui/mod.rs +++ b/crates/aranet-cli/src/gui/mod.rs @@ -36,6 +36,7 @@ use aranet_store::default_db_path; use eframe::egui::{self, IconData}; use tokio::sync::mpsc; use tracing::{debug, info, warn}; +use tracing_subscriber::EnvFilter; use aranet_core::messages::{Command, SensorEvent}; @@ -95,6 +96,38 @@ impl GuiOptions { } } +/// The GUI's log filter: `rust_log`, the value of `RUST_LOG`, when it holds anything, and +/// otherwise errors only. +/// +/// That is the filter `tracing_subscriber::fmt::init()` builds, with one line taken out +/// of the default: the error that btleplug 0.13.5 logs on macOS for every disconnect +/// that CoreBluetooth confirms. `crate::log_filter` says where the line comes from. A +/// `RUST_LOG` of the user's own is used as it is and still shows the line. +/// So does one that holds no valid directive: `EnvFilter::new` then falls back to errors +/// only by itself, as `fmt::init()` did, and that fallback does not carry the directive. +/// (The CLI treats a `RUST_LOG` that does not parse as unset.) +/// +/// When aranet moves to a btleplug release that no longer logs the line, the branch for +/// an empty `RUST_LOG` goes, and this function is `EnvFilter::new(rust_log)` again. +fn gui_log_filter(rust_log: &str) -> EnvFilter { + if rust_log.is_empty() { + EnvFilter::new(crate::log_filter::default_directives("error")) + } else { + EnvFilter::new(rust_log) + } +} + +/// Start logging to stdout, with the filter that `gui_log_filter` builds from `RUST_LOG`. +/// +/// This is `tracing_subscriber::fmt::init()` written out, so that the filter can differ +/// from the library's. Like `init()`, it panics if a global logger is already installed. +fn init_logging() { + let rust_log = std::env::var(EnvFilter::DEFAULT_ENV).unwrap_or_default(); + tracing_subscriber::fmt() + .with_env_filter(gui_log_filter(&rust_log)) + .init(); +} + /// Run the GUI application. /// /// This is the main entry point for the GUI. It: @@ -103,7 +136,7 @@ impl GuiOptions { /// 3. Spawns the background sensor worker /// 4. Runs the egui/eframe main loop pub fn run() -> Result<()> { - tracing_subscriber::fmt::init(); + init_logging(); // Load config to get service URL let config = Config::load_or_default()?; @@ -276,7 +309,7 @@ pub fn run() -> Result<()> { /// /// This allows running in demo mode with mock data for screenshots. pub fn run_with_options(options: GuiOptions) -> Result<()> { - tracing_subscriber::fmt::init(); + init_logging(); if options.demo { info!("Running in demo mode with mock data"); @@ -487,3 +520,44 @@ pub fn run_with_options(options: GuiOptions) -> Result<()> { Ok(()) } + +#[cfg(test)] +mod tests { + use super::*; + + use crate::log_filter::testing::{ + lines_shown_by, shows_disconnect_error, without_disconnect_error, + }; + + /// With `RUST_LOG` unset or empty the GUI logs errors only, as `fmt::init()` did, + /// without the error that btleplug logs on macOS for every disconnect. + #[test] + fn the_default_gui_log_leaves_out_btleplugs_disconnect_error() { + let errors = lines_shown_by(EnvFilter::new("error")); + assert!(shows_disconnect_error(&errors), "{errors:?}"); + + assert_eq!( + lines_shown_by(gui_log_filter("")), + without_disconnect_error(errors) + ); + } + + /// A `RUST_LOG` of the user's own is used as it is, as `fmt::init()` used it, so it + /// still shows the line that the default hides. + #[test] + fn rust_log_replaces_the_default_gui_log_filter() { + for rust_log in ["warn", "btleplug=trace", "aranet_core=debug"] { + assert_eq!( + lines_shown_by(gui_log_filter(rust_log)), + lines_shown_by(EnvFilter::new(rust_log)), + "RUST_LOG={rust_log}" + ); + } + let shown = lines_shown_by(gui_log_filter("warn")); + assert!(shows_disconnect_error(&shown), "{shown:?}"); + // No valid directive: the library's own fallback to errors only, with the line. + let shown = lines_shown_by(gui_log_filter("aranet_core=loud")); + assert!(shows_disconnect_error(&shown), "{shown:?}"); + assert_eq!(shown, lines_shown_by(EnvFilter::new("error"))); + } +} diff --git a/crates/aranet-cli/src/lib.rs b/crates/aranet-cli/src/lib.rs index 9b1f9d6..fb79b6b 100644 --- a/crates/aranet-cli/src/lib.rs +++ b/crates/aranet-cli/src/lib.rs @@ -116,3 +116,8 @@ pub mod tui; // GUI module - publicly exposed for aranet-gui crate to use #[cfg(feature = "gui")] pub mod gui; + +// The default log filter. The library needs it only for the GUI; the `aranet` binary +// compiles the same file for the CLI. The file's own comment says why. +#[cfg(feature = "gui")] +mod log_filter; diff --git a/crates/aranet-cli/src/log_filter.rs b/crates/aranet-cli/src/log_filter.rs new file mode 100644 index 0000000..4fd8634 --- /dev/null +++ b/crates/aranet-cli/src/log_filter.rs @@ -0,0 +1,174 @@ +//! The default log filter of the `aranet` commands and the GUI: the CLI uses it under +//! `--quiet` and when neither `--verbose` nor `RUST_LOG` chooses a filter, the GUI when +//! `RUST_LOG` is unset or empty. +//! +//! This file is a module of two crates. The library compiles it for the GUI (feature +//! `gui`), and the `aranet` binary compiles it again for the CLI (feature `cli`): the +//! binary cannot call a private function of the library, and the filter is not part of +//! the library's public API. Everything in this file must therefore be used by both. An +//! item that only one of them uses is dead code in the other, and clippy fails on it. + +/// Turns off the log target of btleplug's CoreBluetooth peripheral module. +/// +/// On macOS, btleplug 0.13.5 logs `Shouldn't get anything but Ok!` at error level for +/// every disconnect that CoreBluetooth confirms, and then returns `Ok` +/// (btleplug 0.13.5 `src/corebluetooth/peripheral.rs:468-476`). The disconnect's own +/// reply is answered with "Device disconnected", like every other pending operation +/// (`src/corebluetooth/internal.rs:678-698`), and `disconnect()` logs any reply but `Ok` +/// as an error. Every command that connects ends with a disconnect, so without this +/// directive each of them would log an error after it had succeeded. +/// +/// The line is that module's only warning or error. The target is not widened to +/// `btleplug`: other btleplug modules warn when Bluetooth is off or not permitted and +/// when a characteristic discovery fails, and those warnings are true. btleplug has the +/// module only on Apple platforms, so the directive does nothing on Linux and Windows. +/// +/// Remove the directive when aranet moves to a btleplug release that no longer logs the +/// line. +const BTLEPLUG_DISCONNECT_ERROR_OFF: &str = "btleplug::corebluetooth::peripheral=off"; + +/// The directives of the default filter: `level` for every target, without btleplug's +/// disconnect error. The CLI builds its default and its `--quiet` filter from them, the +/// GUI the filter it uses when `RUST_LOG` is unset or empty. +pub(crate) fn default_directives(level: &str) -> String { + format!("{level},{BTLEPLUG_DISCONNECT_ERROR_OFF}") +} + +/// What the tests of the CLI's and the GUI's filters share: a fixed set of log lines, and +/// which of them a filter shows. +#[cfg(test)] +pub(crate) mod testing { + use std::sync::{Arc, Mutex, OnceLock}; + + use tracing_subscriber::EnvFilter; + + /// How btleplug's disconnect error starts, as `lines_shown_by` returns it. + const DISCONNECT_ERROR: &str = "ERROR btleplug::corebluetooth::peripheral: "; + + #[derive(Clone, Default)] + struct Captured(Arc>>); + + impl std::io::Write for Captured { + fn write(&mut self, buf: &[u8]) -> std::io::Result { + self.0.lock().unwrap().extend_from_slice(buf); + Ok(buf.len()) + } + fn flush(&mut self) -> std::io::Result<()> { + Ok(()) + } + } + + /// Keep a second, silent dispatcher registered for the rest of the test run. + /// + /// Tests on several threads call `lines_shown_by`, each with its own filter, and all + /// of them reach the log statements in it. tracing caches, for the whole process, + /// whether any subscriber wants a statement. While only one dispatcher is registered, + /// it fills that cache from the calling thread's subscriber alone and without a lock, + /// so the answer can overwrite the one just computed for a subscriber that another + /// thread registered. With a second dispatcher always registered, the answer is + /// computed over all of them, under the lock that registering takes. aranet-service's + /// tests keep one for the same reason. + fn register_silent_dispatcher() { + static SILENT: OnceLock = OnceLock::new(); + SILENT.get_or_init(|| tracing::Dispatch::new(tracing::subscriber::NoSubscriber::new())); + } + + /// Logs a fixed set of lines under a subscriber with `filter`, and returns the lines + /// the subscriber wrote, each as `LEVEL target: message`. + /// + /// The set has btleplug's disconnect error and an info line from the same module, + /// warnings and errors from btleplug's other CoreBluetooth modules, an error from the + /// crate's root and from its other backends, and lines of aranet's own. + /// + /// btleplug logs through the `log` crate. The bridge that the subscriber's `init` + /// installs asks the subscriber about each record with the record's own target + /// (tracing-log 0.2.0 `src/log_tracer.rs:170-201`, with the metadata that + /// `src/lib.rs:227-242` builds), so a filter treats these events as it treats + /// btleplug's lines. + pub(crate) fn lines_shown_by(filter: EnvFilter) -> Vec { + register_silent_dispatcher(); + let captured = Captured::default(); + let writer = captured.clone(); + let subscriber = tracing_subscriber::fmt() + .without_time() + .with_env_filter(filter) + .with_ansi(false) + .with_writer(move || writer.clone()) + .finish(); + let _guard = tracing::subscriber::set_default(subscriber); + + tracing::error!( + target: "btleplug::corebluetooth::peripheral", + "Shouldn't get anything but Ok!" + ); + tracing::info!( + target: "btleplug::corebluetooth::peripheral", + "Event receiver died, breaking out of corebluetooth device loop." + ); + tracing::warn!( + target: "btleplug::corebluetooth::internal", + "Adapter powered off, canceling all pending operations" + ); + tracing::error!( + target: "btleplug::corebluetooth::internal", + "Error sending notification event" + ); + tracing::warn!( + target: "btleplug::corebluetooth::central_delegate", + "Error discovering characteristics" + ); + tracing::error!( + target: "btleplug::corebluetooth::central_delegate", + "an error from the delegate" + ); + tracing::error!(target: "btleplug::corebluetooth::adapter", "an error from the adapter"); + tracing::error!(target: "btleplug::corebluetooth", "an error from the backend"); + tracing::error!(target: "btleplug", "an error from the crate root"); + tracing::error!(target: "btleplug::bluez::peripheral", "an error from BlueZ"); + tracing::error!(target: "btleplug::winrtble::peripheral", "an error from WinRT"); + tracing::warn!(target: "aranet_core::link", "a warning from aranet-core"); + tracing::error!(target: "aranet_cli::gui", "an error from aranet-cli"); + tracing::info!(target: "aranet_core::link", "an info line from aranet-core"); + + let text = String::from_utf8(captured.0.lock().unwrap().clone()).unwrap(); + text.lines() + .map(|line| line.trim_start().to_string()) + .collect() + } + + /// Whether `lines`, as `lines_shown_by` returns them, hold btleplug's disconnect error. + pub(crate) fn shows_disconnect_error(lines: &[String]) -> bool { + lines.iter().any(|line| line.starts_with(DISCONNECT_ERROR)) + } + + /// `lines` without btleplug's disconnect error. + pub(crate) fn without_disconnect_error(lines: Vec) -> Vec { + lines + .into_iter() + .filter(|line| !line.starts_with(DISCONNECT_ERROR)) + .collect() + } +} + +#[cfg(test)] +mod tests { + use tracing_subscriber::EnvFilter; + + use super::default_directives; + use super::testing::{lines_shown_by, shows_disconnect_error, without_disconnect_error}; + + /// At the CLI's level and at the GUI's, the default shows what the level alone shows + /// minus one line. btleplug's other modules and aranet's own lines are untouched. + #[test] + fn the_default_hides_only_btleplugs_disconnect_error() { + // Of the 14 lines `lines_shown_by` logs, 12 are warnings or errors and 9 are errors. + for (level, lines_at_level) in [("warn", 12), ("error", 9)] { + let plain = lines_shown_by(EnvFilter::new(level)); + assert_eq!(plain.len(), lines_at_level, "{level}: {plain:?}"); + assert!(shows_disconnect_error(&plain), "{level}: {plain:?}"); + + let shown = lines_shown_by(EnvFilter::new(default_directives(level))); + assert_eq!(shown, without_disconnect_error(plain), "{level}"); + } + } +} diff --git a/crates/aranet-cli/src/main.rs b/crates/aranet-cli/src/main.rs index afad1cf..0250861 100644 --- a/crates/aranet-cli/src/main.rs +++ b/crates/aranet-cli/src/main.rs @@ -17,6 +17,9 @@ mod cli; mod commands; #[cfg(feature = "cli")] mod format; +// Also a module of the library, for the GUI. The file's own comment says why. +#[cfg(feature = "cli")] +mod log_filter; #[cfg(feature = "cli")] mod style; #[cfg(feature = "cli")] @@ -128,13 +131,8 @@ async fn main() -> Result<()> { let mut config = Config::load_or_default()?; // Initialize tracing (write to stderr so stdout is clean for data) - let filter = if cli.quiet { - EnvFilter::new("warn") - } else if cli.verbose { - EnvFilter::new("debug") - } else { - EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("warn")) - }; + let rust_log = std::env::var(EnvFilter::DEFAULT_ENV).ok(); + let filter = cli_log_filter(cli.quiet, cli.verbose, rust_log.as_deref()); tracing_subscriber::fmt() .with_env_filter(filter) @@ -366,6 +364,31 @@ async fn main() -> Result<()> { Ok(()) } +/// The log filter of a CLI command. +/// +/// `--quiet` and `--verbose` each fix the filter. Without them a `RUST_LOG` that parses is +/// used as it is, and otherwise the filter is the default: warnings and errors. +/// +/// `--quiet` and the default leave out one line, through `log_filter::default_directives`: +/// the error that btleplug 0.13.5 logs on macOS for every disconnect that CoreBluetooth +/// confirms, which would follow every successful command that connects. `--verbose` and a +/// `RUST_LOG` of the user's own still show it. +/// +/// When aranet moves to a btleplug release that no longer logs the line, both calls of +/// `log_filter::default_directives` go back to `"warn"`. +#[cfg(feature = "cli")] +fn cli_log_filter(quiet: bool, verbose: bool, rust_log: Option<&str>) -> EnvFilter { + if quiet { + EnvFilter::new(log_filter::default_directives("warn")) + } else if verbose { + EnvFilter::new("debug") + } else { + rust_log + .and_then(|directives| EnvFilter::try_new(directives).ok()) + .unwrap_or_else(|| EnvFilter::new(log_filter::default_directives("warn"))) + } +} + #[cfg(feature = "cli")] fn handle_alias_command(action: &AliasSubcommand, quiet: bool) -> Result<()> { let alias_action = match action { @@ -674,6 +697,10 @@ fn print_examples() { mod tests { use super::*; + use crate::log_filter::testing::{ + lines_shown_by, shows_disconnect_error, without_disconnect_error, + }; + // ======================================================================== // resolve_format_with_config tests // ======================================================================== @@ -848,4 +875,55 @@ mod tests { "{text}" ); } + + // ======================================================================== + // cli_log_filter tests + // ======================================================================== + + /// `--quiet` and the default show warnings and errors, without the error that + /// btleplug logs on macOS for every disconnect. `--quiet` ignores `RUST_LOG` and wins + /// over `--verbose`; a `RUST_LOG` that does not parse gives the default. + #[test] + fn test_cli_log_filter_quiet_and_default_hide_btleplugs_disconnect_error() { + let warnings = lines_shown_by(EnvFilter::new("warn")); + assert!(shows_disconnect_error(&warnings), "{warnings:?}"); + let expected = without_disconnect_error(warnings); + + for (quiet, verbose, rust_log) in [ + (true, false, None), + (true, false, Some("debug")), + (true, true, None), + (false, false, None), + (false, false, Some("aranet_core=loud")), + ] { + assert_eq!( + lines_shown_by(cli_log_filter(quiet, verbose, rust_log)), + expected, + "quiet={quiet} verbose={verbose} RUST_LOG={rust_log:?}" + ); + } + } + + /// `--verbose` and a `RUST_LOG` of the user's own are used as they are, so both + /// still show the line that the default hides. + #[test] + fn test_cli_log_filter_verbose_and_rust_log_show_btleplugs_disconnect_error() { + for (verbose, rust_log, same_as) in [ + (true, None, "debug"), + (true, Some("error"), "debug"), + (false, Some("warn"), "warn"), + (false, Some("btleplug=trace"), "btleplug=trace"), + ] { + let shown = lines_shown_by(cli_log_filter(false, verbose, rust_log)); + assert!( + shows_disconnect_error(&shown), + "verbose={verbose} RUST_LOG={rust_log:?}: {shown:?}" + ); + assert_eq!( + shown, + lines_shown_by(EnvFilter::new(same_as)), + "verbose={verbose} RUST_LOG={rust_log:?}" + ); + } + } } diff --git a/crates/aranet-core/examples/discover_services.rs b/crates/aranet-core/examples/discover_services.rs index 24c8afd..8c52aa4 100644 --- a/crates/aranet-core/examples/discover_services.rs +++ b/crates/aranet-core/examples/discover_services.rs @@ -77,7 +77,12 @@ async fn main() -> Result<(), Box> { std::process::exit(1); } }; - let name = p.properties().await?.and_then(|props| props.local_name); + let name = p + .properties() + .await? + .as_ref() + .and_then(aranet_core::peripheral_name) + .map(str::to_owned); println!("\nFound: {}", name.as_deref().unwrap_or(&identifier)); diff --git a/crates/aranet-core/examples/lifecycle_soak.rs b/crates/aranet-core/examples/lifecycle_soak.rs index 23cfc03..c67e897 100644 --- a/crates/aranet-core/examples/lifecycle_soak.rs +++ b/crates/aranet-core/examples/lifecycle_soak.rs @@ -245,16 +245,9 @@ fn parse_args(args: impl IntoIterator) -> Result, St Ok(Some(parsed)) } -/// Whether `name` is `query`, ignoring case, or either half of CoreBluetooth's -/// combined `" []"`. +/// Whether `name` is `query`, ignoring case. Only the whole name counts. fn name_matches(name: &str, query: &str) -> bool { name.eq_ignore_ascii_case(query) - || name - .strip_suffix(']') - .and_then(|rest| rest.split_once(" [")) - .is_some_and(|(gap, advertised)| { - gap.eq_ignore_ascii_case(query) || advertised.eq_ignore_ascii_case(query) - }) } /// Which driver a link cut or an event belongs to. @@ -650,8 +643,10 @@ impl Snapshot { /// connected, each with the identifier it matched. A sensor that the adapter /// doesn't list, or whose query doesn't answer within 2 s, counts as not /// connected: on macOS a disconnect removes the peripheral from the adapter's -/// list until a scan finds it again, and a handle kept from before the -/// disconnect gets no answer. `Err` means the adapter couldn't list its +/// list until a scan finds it again, and until then a handle kept from before +/// the disconnect is answered "not connected" at once (btleplug 0.13.5 +/// `src/corebluetooth/internal.rs:1318-1332`; 0.11.8 gave it no answer). The +/// 2 s limit is a guard. `Err` means the adapter couldn't list its /// peripherals. async fn connected_peripherals(ids: &[String]) -> Result, String> { let adapter = get_adapter() @@ -1334,12 +1329,13 @@ mod tests { } #[test] - fn name_matching_is_exact_but_accepts_either_half_of_a_corebluetooth_name() { + fn name_matching_is_exact_apart_from_case() { assert!(name_matches("Aranet2 2751B", "aranet2 2751b")); assert!(!name_matches("Aranet2 2751B", "2751B")); - assert!(name_matches("Kitchen [Aranet4 1A2B3]", "Aranet4 1A2B3")); - assert!(name_matches("Kitchen [Aranet4 1A2B3]", "kitchen")); - assert!(!name_matches("Kitchen [Aranet4 1A2B3]", "Aranet4")); + // A bracketed part is part of the name like any other. + assert!(name_matches("Hall [Aranet2 2751B]", "hall [aranet2 2751b]")); + assert!(!name_matches("Hall [Aranet2 2751B]", "hall")); + assert!(!name_matches("Hall [Aranet2 2751B]", "aranet2 2751b")); } #[test] diff --git a/crates/aranet-core/src/connector.rs b/crates/aranet-core/src/connector.rs index 22c0168..c0328e7 100644 --- a/crates/aranet-core/src/connector.rs +++ b/crates/aranet-core/src/connector.rs @@ -62,17 +62,39 @@ pub(crate) async fn release_link( .map_err(std::io::Error::from)? } -/// Whether closing a link that has already dropped on its own times out on -/// this platform. Where it does, a close that times out usually means only -/// that the link had dropped, not that the sensor is still connected. True -/// only on macOS: once CoreBluetooth reports a link down, btleplug's -/// CoreBluetooth backend forgets the peripheral and never answers a disconnect -/// for it, so the close runs into its time limit. Links to unpaired sensors -/// can drop on their own there a few minutes after they come up. +/// Whether a close that times out counts as expected on this platform. It +/// only sets the log level of a failed `release_link` in +/// `log_failed_release`, which `ReconnectingDevice` and `DeviceManager` +/// call: debug where this is true and the close timed out, a warning in +/// every other case. True only on macOS. /// -/// Workaround for btleplug 0.11.8 -/// (); re-check when -/// upgrading btleplug. +/// It was written for btleplug 0.11.8. Once CoreBluetooth reports a link +/// down, btleplug's CoreBluetooth backend forgets the peripheral, and 0.11.8 +/// never answered a disconnect for a peripheral it had forgotten. So closing +/// a link that had already dropped on its own always ran into its time +/// limit, and a close that timed out usually meant only that the link had +/// dropped, not that the sensor was still connected. With 0.11.8, links to +/// unpaired sensors were seen to drop on their own on macOS a few minutes +/// after they came up. +/// +/// btleplug 0.13.5 still forgets the peripheral +/// (`src/corebluetooth/internal.rs:1156-1181`), but it answers that +/// disconnect with `Ok` at once for as long as it has no entry for the +/// sensor (`src/corebluetooth/internal.rs:1307-1316`). By its source, +/// closing a link that has dropped on its own therefore no longer times +/// out. The source can't settle one case: a scan finds the sensor again +/// before the old handle is closed. btleplug then has a new entry for the +/// sensor, and the close asks CoreBluetooth to cancel that entry's +/// connection and waits for the disconnect callback +/// (`src/corebluetooth/internal.rs:1309-1312`). Whether CoreBluetooth sends +/// that callback for a peripheral that isn't connected is not in btleplug's +/// source. +/// +/// Hardware check H2 of the btleplug 0.13.5 upgrade (2026-10-11, on macOS: a +/// sensor whose link had ended and that a scan had found again) saw the +/// close through the old handle get no answer before its time limit. So the +/// classifier still has one real case: a close of a dropped link after a +/// scan has found the sensor again. const CLOSES_TIME_OUT_AFTER_DROP: bool = cfg!(target_os = "macos"); /// Whether `error`, from a failed `release_link`, is expected and so no sign diff --git a/crates/aranet-core/src/device.rs b/crates/aranet-core/src/device.rs index 3d76386..7cc8d95 100644 --- a/crates/aranet-core/src/device.rs +++ b/crates/aranet-core/src/device.rs @@ -17,7 +17,7 @@ use uuid::Uuid; use crate::error::{Error, Result}; use crate::scan::ScanOptions; use crate::traits::AranetDevice; -use crate::util::{create_identifier, format_peripheral_id}; +use crate::util::{create_identifier, format_peripheral_id, peripheral_name}; use crate::uuid::{ BATTERY_LEVEL, BATTERY_SERVICE, CURRENT_READINGS_DETAIL, CURRENT_READINGS_DETAIL_ALT, DEVICE_INFO_SERVICE, DEVICE_NAME, FIRMWARE_REVISION, GAP_SERVICE, HARDWARE_REVISION, @@ -198,6 +198,16 @@ pub struct ConnectionConfig { pub write_timeout: Duration, /// Timeout for service discovery after connection. /// + /// On macOS this limits the service discovery itself. With btleplug + /// 0.13.5 a connect ends when the link is up + /// (`src/corebluetooth/peripheral.rs:433-456`) and the services are + /// discovered in a step of their own (`:479-500`), so the link has + /// `connection_timeout` to come up and the discovery has this limit. A + /// discovery that takes longer fails the connect with a "discover + /// services" timeout. With btleplug 0.11.8 the discovery ran inside the + /// connect, under `connection_timeout`, and this limit had no effect on + /// macOS. + /// /// On Linux, when BlueZ is still discovering the services of a device it /// has just connected (a first connection to a sensor with many /// characteristics, such as an Aranet4), a connect waits for BlueZ to @@ -602,7 +612,10 @@ impl Device { characteristics_cache.len() ); - let name = properties.as_ref().and_then(|p| p.local_name.clone()); + let name = properties + .as_ref() + .and_then(peripheral_name) + .map(str::to_owned); // Get address - on macOS this may be 00:00:00:00:00:00, so we use peripheral ID as fallback let address = properties @@ -635,8 +648,10 @@ impl Device { /// /// Returns `false` if the Bluetooth stack reports an error or doesn't answer /// within the connection's `validation_timeout` (3 s by default, set with - /// [`ConnectionConfig::validation_timeout`]). On macOS the stack stops - /// answering once the sensor has dropped the connection. + /// [`ConnectionConfig::validation_timeout`]). On macOS the limit is only a + /// guard: once the sensor has dropped the connection, btleplug 0.13.5 + /// answers `false` at once (`src/corebluetooth/internal.rs:1318-1332`), + /// where 0.11.8 gave no answer. /// /// Note: This only checks the BLE stack's connection state, which may be stale, /// especially on macOS. For a more reliable check, use [`Self::validate_connection`]. diff --git a/crates/aranet-core/src/lib.rs b/crates/aranet-core/src/lib.rs index 74b831c..4cec9fe 100644 --- a/crates/aranet-core/src/lib.rs +++ b/crates/aranet-core/src/lib.rs @@ -246,7 +246,7 @@ pub use reconnect::{ReconnectOptions, ReconnectingDevice}; pub use retry::{RetryConfig, with_retry}; pub use streaming::{ReadingStream, StreamOptions, StreamOptionsBuilder}; pub use thresholds::{Co2Level, ThresholdConfig, Thresholds}; -pub use util::{create_identifier, format_peripheral_id}; +pub use util::{create_identifier, format_peripheral_id, peripheral_name}; pub use validation::{ReadingValidator, ValidationResult, ValidationWarning}; // Re-export from aranet-types diff --git a/crates/aranet-core/src/link.rs b/crates/aranet-core/src/link.rs index b009989..890cf62 100644 --- a/crates/aranet-core/src/link.rs +++ b/crates/aranet-core/src/link.rs @@ -52,17 +52,22 @@ pub(crate) trait GattLink: Clone + Send + Sync + 'static { &self, ) -> impl Future>> + Send; - /// Whether the Bluetooth stack reports the link as up. On macOS nobody - /// answers this once CoreBluetooth has dropped the peripheral, so callers - /// use this module's time-limited `is_connected` function instead. + /// Whether the Bluetooth stack reports the link as up. Callers use this + /// module's time-limited `is_connected` function instead, as a guard + /// against a stack that doesn't answer. On macOS, btleplug 0.11.8 gave no + /// answer once its CoreBluetooth backend had forgotten the peripheral; + /// 0.13.5 answers "not connected" at once + /// (`src/corebluetooth/internal.rs:1318-1332`). fn is_connected(&self) -> impl Future> + Send; /// Whether the connection goes through BlueZ. There `connect` doesn't /// return when the link comes up: BlueZ answers `Device1.Connect` only /// once the ATT channel is up, a few seconds later, and bluez-async then - /// waits up to 5 s more for BlueZ to resolve the services. So a `connect` - /// can run out of time with the link already up and BlueZ still setting - /// up the ATT channel or discovering. + /// waits up to 30 s more for BlueZ to resolve the services (bluez-async + /// 0.9.0 `src/lib.rs:61`). So a `connect` can run out of time with the + /// link already up and BlueZ still setting up the ATT channel or + /// discovering. Under a limit of 30 s or less, such as the 15 s default, + /// that is how every connect ends whose discovery outlasts the limit. fn is_bluez(&self) -> bool; /// Enable notifications on `characteristic` (the CCCD write). @@ -436,19 +441,31 @@ pub(crate) async fn connect( /// and discover once more ("reconnect to device", "rediscover services"). /// If that discovery finds none either, fail with a retryable /// `Error::ConnectionFailed` ("the device reported no GATT services"). +/// On macOS the retry doesn't help: the disconnect makes btleplug 0.13.5 +/// forget the peripheral, so the reconnect on the same handle fails at +/// once with a retryable `Error::Bluetooth` ("Peripheral no longer +/// available", `src/corebluetooth/internal.rs:1300-1304`), unless a scan +/// has found the sensor again during the pause. aranet's own callers that +/// retry connect by identifier, so they search for the sensor again. A +/// retry on the same handle (`Device::from_peripheral` and its variants) +/// is refused in the same way until a scan has found the sensor. /// 5. Read the properties, giving up after `read_timeout`. /// /// On BlueZ, a connect (the first one or the retry's) can end while BlueZ is /// still discovering the services on the live link. BlueZ answers /// `Device1.Connect` only once the ATT channel is up, a few seconds after the -/// link, and bluez-async stops waiting for the services 5 s after that answer. -/// A link that comes up late can also use up `connection_timeout` first, while -/// BlueZ is still setting up the ATT channel or discovering; `connect_link` -/// then asks whether the link is up. Either way the discovery after it first -/// waits for BlueZ to finish (`wait_for_bluez_discovery`), and that -/// connection-state query, the wait and the discovery share one -/// `bluez_discovery_limit` (20 s at defaults), whose end fails the connect -/// with a "discover services" (or "rediscover services") timeout. +/// link, and bluez-async then waits up to 30 s for the services +/// (bluez-async 0.9.0 `src/lib.rs:61`). It waited 5 s before btleplug 0.13.5 +/// (). So under a +/// `connection_timeout` of 30 s or less, the 15 s default included, a connect +/// whose discovery is unfinished at that limit runs out of time first, and +/// `connect_link` then asks whether the link is up. bluez-async gives up +/// first ("Service discovery timed out") only under a longer limit. Either +/// way the discovery after it first waits for BlueZ to finish +/// (`wait_for_bluez_discovery`), and that connection-state query, the wait +/// and the discovery share one `bluez_discovery_limit` (20 s at defaults), +/// whose end fails the connect with a "discover services" (or "rediscover +/// services") timeout. /// /// `connect` disconnects the link when any step fails. async fn connect_and_discover( @@ -488,6 +505,25 @@ async fn connect_and_discover( // If service discovery returned nothing, BlueZ may have stale state // from a previous failed connection (e.g., auth failure during GATT // discovery). Disconnect, wait, and retry once with a clean connection. + // + // On macOS, btleplug 0.11.8 never returned an empty set: its connect + // didn't return when the discovery found no services. btleplug 0.13.5 + // does, in three ways. A discovery that CoreBluetooth ends with no error + // and no services succeeds with none + // (`src/corebluetooth/internal.rs:364-365`). A "services changed" + // callback during a discovery can end it with only the services that + // are left, which may be none (`internal.rs:968-985`). And every such + // callback, during a discovery or just after one, empties the set that + // this handle keeps (`internal.rs:986-993`, + // `src/corebluetooth/peripheral.rs:175-177`), which can happen before + // the set is read here. The retry doesn't help there: the disconnect + // makes btleplug forget the peripheral (`internal.rs:1175`), so the + // reconnect on this handle fails at once with "Peripheral no longer + // available" (`internal.rs:1300-1304`), unless a scan has found the + // sensor again during the pause. That error is retryable. aranet's own + // callers that retry connect by identifier, so they search for the + // sensor again; a retry on the same handle is refused in the same way + // until a scan has found the sensor. if services.is_empty() { warn!("Service discovery returned 0 services — retrying with fresh connection"); if let Err(e) = disconnect(link).await { @@ -524,22 +560,40 @@ async fn connect_and_discover( } /// What bluez-async's `connect` fails with when BlueZ hasn't resolved the -/// services 5 s after `Device1.Connect` returned, although the link is up and -/// BlueZ is still discovering (`BluetoothError::ServiceDiscoveryTimedOut`, -/// bluez-async 0.8.2 `src/lib.rs:61`, `:90-92`, `:696-724`). btleplug passes -/// it on as `btleplug::Error::Other` (`src/bluez/adapter.rs:125-129`). No -/// other btleplug backend produces it. aranet-core can't name bluez-async's -/// type (it isn't a dependency), so this matches the message. +/// services 30 s after `Device1.Connect` returned, although the link is up +/// and BlueZ is still discovering (`BluetoothError::ServiceDiscoveryTimedOut`, +/// bluez-async 0.9.0 `src/lib.rs:61`, `:90-92`, `:699-727`). btleplug passes +/// it on as `btleplug::Error::Other` (btleplug 0.13.5 +/// `src/bluez/adapter.rs:182-186`). No other btleplug backend produces it. +/// aranet-core can't name bluez-async's type (it isn't a dependency), so this +/// matches the message. The first call of a connect gets it only under a +/// `connection_timeout` above those 30 s, and a call made again during the +/// wait only under a `discovery_timeout` above them +/// (`wait_for_bluez_discovery`); a limit of 30 s or less ends the call first. const BLUEZ_DISCOVERY_TIMED_OUT: &str = "Service discovery timed out"; /// The least time a connect waits for BlueZ to finish discovering the services -/// once bluez-async has given up, or the connect has run out of time with the -/// link up (BR-25). An Aranet4 that BlueZ hasn't cached needs about 30-48 ATT +/// once the connect has run out of time with the link up, or bluez-async has +/// given up (BR-25). An Aranet4 that BlueZ hasn't cached needs about 30-48 ATT /// requests at 0.3-0.45 s each: 9-22 s from the moment BlueZ answers /// `Device1.Connect`, which on an LE link it does once the ATT channel is up, -/// a few seconds after the link. bluez-async has already waited 5 s of that -/// when it gives up. When the connect runs out of time with the link up, less -/// than 5 s of it has passed, or none if BlueZ hasn't answered yet. +/// a few seconds after the link. +/// +/// Counted from that answer, BlueZ's discovery gets +/// `min(a + 30 s, connection_timeout) + wait - a` in all, where `a` is the +/// time BlueZ took to answer and the 30 s are bluez-async's own wait for the +/// services (bluez-async 0.9.0 `src/lib.rs:61`). At the default limits that +/// is `15 s + 20 s - a`: 33 s when BlueZ answers after 2 s, and little more +/// than this wait alone when it answers just before the connect's limit. If +/// BlueZ hasn't answered by then, the wait also has to cover the rest of the +/// ATT set-up. When bluez-async gives up first, which needs a +/// `connection_timeout` above 30 s, the discovery has already had 30 s. +/// +/// bluez-async waited only 5 s until btleplug 0.13.5 moved to bluez-async +/// 0.9.0 (), and this wait +/// was added to make up for that. It is still needed: a connect whose limit +/// is 30 s or less ends before bluez-async's wait does, and without this wait +/// it would fail and disconnect in the middle of BlueZ's discovery. pub(crate) const BLUEZ_DISCOVERY_MIN_WAIT: Duration = Duration::from_secs(20); /// How long a connect waits for BlueZ to finish discovering the services once @@ -577,10 +631,13 @@ fn is_bluez_in_progress(error: &btleplug::Error) -> bool { #[derive(Debug, Clone, Copy, PartialEq, Eq)] enum BluezWaitReason { /// bluez-async's `connect` gave up waiting for the services, so BlueZ has - /// answered `Device1.Connect`. + /// answered `Device1.Connect`. bluez-async waits 30 s (bluez-async 0.9.0 + /// `src/lib.rs:61`), so this needs a `connection_timeout` above 30 s. DiscoveryTimedOut, - /// The connect ran out of time with the link up. BlueZ may not have - /// answered that `Device1.Connect` yet. + /// The connect ran out of time with the link up. Under a + /// `connection_timeout` of 30 s or less this is the reason for every + /// wait. BlueZ has usually answered that `Device1.Connect` by then, but + /// it may not have answered yet. ConnectTimedOut, } @@ -638,10 +695,12 @@ async fn connect_link( } // BlueZ answers `Device1.Connect` only once the ATT channel is up, a // few seconds after the link, and bluez-async's `connect` then waits - // up to 5 s more for the services. So a link that comes up late in - // `connection_timeout` runs out of time here while BlueZ is still - // setting up the ATT channel or discovering on it. Disconnecting - // would cancel that, and every retry would start it again. + // up to 30 s more for the services (bluez-async 0.9.0 + // `src/lib.rs:61`). So under a `connection_timeout` of 30 s or less, + // every connect whose discovery is unfinished at the limit runs out + // of time here, with BlueZ still setting up the ATT channel or + // discovering on the link. Disconnecting would cancel that, and + // every retry would start it again. Err(timeout @ Error::Timeout { .. }) if link.is_bluez() => { // The query counts against the wait's limit, so the connect still // takes at most `connection_timeout`, and the query and the wait @@ -699,17 +758,32 @@ async fn discover( /// /// Once BlueZ has answered the connect that started the wait, it answers /// `Device1.Connect` at once while the device is connected (`src/device.c`, -/// `dev_connect`), and bluez-async then waits up to 5 s more for -/// `ServicesResolved`, or returns at once if it is already set. If the link -/// has dropped, `Device1.Connect` opens a new one, as the caller's own retry -/// would. +/// `dev_connect`), and bluez-async then waits up to 30 s more for +/// `ServicesResolved` (bluez-async 0.9.0 `src/lib.rs:61`), or returns at once +/// if it is already set. Those 30 s are longer than the default 20 s wait, so +/// at the default limits the wait makes one such call: BlueZ finishes during +/// it, or the caller's deadline ends it. Another call after a "Service +/// discovery timed out" needs a `discovery_timeout` above 30 s. +/// +/// If the link has dropped, a `Device1.Connect` made after the drop opens a +/// new one, as the caller's own retry would. A call that is already waiting +/// for the services does not notice a drop (bluez-async 0.9.0 +/// `src/lib.rs:711-726`), and at the default limits its 30 s outlast the +/// wait. So there a link that drops after BlueZ has accepted a call of the +/// wait is not reopened. One that drops earlier, while BlueZ still refuses +/// with `In Progress` (below), is: the next call BlueZ accepts opens a new +/// link. /// /// After a connect timeout (`BluezWaitReason::ConnectTimedOut`), BlueZ may not /// have answered the timed-out `Device1.Connect` yet, and until it does it /// refuses the next one with `In Progress`. Then the wait asks again after -/// `BLUEZ_IN_PROGRESS_PAUSE`. After bluez-async's discovery timeout BlueZ has -/// answered, so an `In Progress` there comes from another connect to the -/// device or a pairing of it, and ends the wait. +/// `BLUEZ_IN_PROGRESS_PAUSE`. Under a `connection_timeout` of 30 s or less +/// every wait starts this way, so there an `In Progress` that comes from +/// another connect to the device or a pairing of it is asked again as well, +/// until the caller's deadline. After bluez-async's discovery timeout, which +/// needs a longer `connection_timeout`, BlueZ has answered, so an +/// `In Progress` there comes from another connect to the device or a pairing +/// of it, and ends the wait. /// /// Any other result ends the wait. The caller limits it. async fn wait_for_bluez_discovery( @@ -746,6 +820,7 @@ mod tests { use crate::device::ConnectionConfig; use crate::error::{ConnectionFailureReason, Error}; use crate::test_support::within; + use crate::util::peripheral_name; /// Run a connect on `fake` that must fail, with the default config and the /// test's runtime for cleanup, and return its error. @@ -791,8 +866,12 @@ mod tests { open.pending.disarm(); assert_eq!(open.services, aranet_services()); + // The name, read as every other place in the crate reads it. The + // test double reports it in both name fields: with `local_name` + // alone this would fail on Linux and Windows, where + // `peripheral_name` takes only the advertised name. assert_eq!( - open.properties.and_then(|p| p.local_name).as_deref(), + open.properties.as_ref().and_then(peripheral_name), Some("Aranet4 12345") ); tokio::time::sleep(Duration::from_secs(1)).await; @@ -1048,6 +1127,42 @@ mod tests { .await; } + /// A reconnect that is refused at once during the zero-services retry + /// fails the connect with that Bluetooth error as soon as the retry's 2 s + /// pause is over, and disconnects before the error returns. This is what + /// the retry meets on macOS with btleplug 0.13.5: the disconnect before + /// the pause makes btleplug forget the peripheral, and a connect on the + /// same handle then fails at once with "Peripheral no longer available" + /// (`src/corebluetooth/internal.rs:1300-1304`). The test pins what the + /// caller gets in that case. It adds no code path: the retry is the one + /// that `failed_reconnect_during_retry_disconnects` covers for a + /// reconnect that never answers, and it is unchanged. + #[tokio::test(start_paused = true)] + async fn reconnect_refused_during_retry_fails_after_the_pause() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.service_rounds([BTreeSet::new()]); + fake.script_connect([Outcome::Ok, Outcome::Fail]); + let start = Instant::now(); + + let error = failed_connect(&fake).await; + + assert!(matches!(error, Error::Bluetooth(_)), "got {error:?}"); + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::Discover, + Call::Disconnect, + Call::Connect, + Call::Disconnect, + ] + ); + assert_eq!(start.elapsed(), Duration::from_secs(2)); + }) + .await; + } + /// The rediscovery of the zero-services retry is limited by /// `discovery_timeout`, and running out is reported as "rediscover /// services". @@ -1192,8 +1307,11 @@ mod tests { .await; } - /// A connection-state query that the stack never answers (CoreBluetooth - /// after the sensor has gone) reports `false` after `validation_timeout`. + /// A connection-state query that the stack never answers reports `false` + /// after `validation_timeout`. The limit is a guard against a stack that + /// has stopped answering. btleplug 0.11.8 gave no answer on macOS once it + /// had forgotten the peripheral; 0.13.5 answers "not connected" at once + /// there (`src/corebluetooth/internal.rs:1318-1332`). #[tokio::test(start_paused = true)] async fn is_connected_reports_false_when_the_stack_never_answers() { within(Duration::from_secs(600), async { @@ -1643,14 +1761,23 @@ mod tests { } } -/// BR-25: bluez-async's `connect` gives BlueZ 5 s to resolve the services +/// BR-25: bluez-async's `connect` gives BlueZ 30 s to resolve the services /// after BlueZ answers `Device1.Connect`, which on an LE link it does once the -/// ATT channel is up, a few seconds after the link. A sensor with a large GATT -/// table and a slow link, such as an Aranet4 that BlueZ hasn't cached yet, -/// needs longer, and BlueZ keeps discovering on the live link after -/// bluez-async has given up. When the link itself is slow to come up, the -/// connect's own time limit can run out first, again with the link up and -/// BlueZ still setting up the ATT channel or discovering on it. +/// ATT channel is up, a few seconds after the link (bluez-async 0.9.0 +/// `src/lib.rs:61`). It gave 5 s before btleplug 0.13.5 +/// (). A connect's own +/// time limit is 15 s by default, so when a sensor with a large GATT table +/// and a slow link, such as an Aranet4 that BlueZ hasn't cached yet, needs +/// longer than that, the connect's limit runs out first, with the link up +/// and BlueZ still setting up the ATT channel or discovering on it. The +/// connect then waits for BlueZ by asking it to connect again. bluez-async +/// gives up before the connect's limit only when that limit is longer than +/// its 30 s; the tests of that path set such a limit (`LONG_CONNECT_LIMIT`, +/// 90 s, or `ConnectionConfig::challenging_environment()`). Either way BlueZ +/// keeps discovering on the live link. +/// +/// The fake's `fake::BLUEZ_ASYNC_WAIT` models bluez-async's wait, and its +/// doc says how a first connect must be scripted. #[cfg(test)] mod bluez_discovery_tests { use std::collections::BTreeSet; @@ -1660,13 +1787,14 @@ mod bluez_discovery_tests { use tokio::time::Instant; use super::connect; - use super::fake::{BLUEZ_ASYNC_WAIT, Call, FakeGatt, Outcome}; + use super::fake::{BLUEZ_ASYNC_WAIT, BLUEZ_DBUS_TIMEOUT, Call, FakeGatt, Outcome}; use super::tests::assert_timeout; use crate::device::ConnectionConfig; use crate::error::{Error, Result}; use crate::test_support::within; - /// The least time a connect waits for BlueZ once bluez-async has given up + /// The least time a connect waits for BlueZ once the connect has run out + /// of time with the link up, or bluez-async has given up /// (`BLUEZ_DISCOVERY_MIN_WAIT`). const MIN_WAIT: Duration = Duration::from_secs(20); @@ -1674,6 +1802,14 @@ mod bluez_discovery_tests { /// when BlueZ answered `In Progress` (`BLUEZ_IN_PROGRESS_PAUSE`). const IN_PROGRESS_PAUSE: Duration = Duration::from_secs(1); + /// A connect limit longer than bluez-async's 30 s wait for the services + /// (`BLUEZ_ASYNC_WAIT`). Only under such a limit can bluez-async's own + /// "Service discovery timed out" end a first connect: under the default + /// 15 s, and under `aranet watch`'s 30 s, the connect's limit ends it + /// first. Most tests of the paths that start with the library's timeout + /// use this limit; the others set a longer one of their own. + const LONG_CONNECT_LIMIT: Duration = Duration::from_secs(45); + /// Connect `fake` with `config` and the test's runtime for cleanup, and /// disarm the link if the connect succeeds. pub(super) async fn connect_with(fake: &FakeGatt, config: &ConnectionConfig) -> Result<()> { @@ -1706,8 +1842,13 @@ mod bluez_discovery_tests { } } - /// A connect that bluez-async gives up on while BlueZ is still discovering - /// asks again until BlueZ has resolved the services, then discovers them. + /// Under a connect limit longer than bluez-async's wait, a connect that + /// bluez-async gives up on while BlueZ is still discovering asks again + /// until BlueZ has resolved the services, then discovers them. The second + /// "Service discovery timed out" here comes from a re-ask inside the + /// wait, which needs a `discovery_timeout` above bluez-async's 30 s too: + /// at the default limits the wait's own limit ends the first re-ask + /// (`a_connect_timeout_with_the_link_up_gives_up_after_the_wait`). #[tokio::test(start_paused = true)] async fn waits_while_bluez_is_still_discovering() { within(Duration::from_secs(600), async { @@ -1717,12 +1858,18 @@ mod bluez_discovery_tests { Outcome::DiscoveryTimedOut, Outcome::Ok, ]); + let config = ConnectionConfig::default() + .connection_timeout(LONG_CONNECT_LIMIT) + .discovery_timeout(Duration::from_secs(70)); let start = Instant::now(); - connect_with(&fake, &ConnectionConfig::default()) + connect_with(&fake, &config) .await .expect("the connect should wait for BlueZ's service discovery"); + // The library gives up at 30 s. The wait's limit is then 100 s + // (30 + 70): the first re-ask gives up at 60 s (30 + 30) and the + // second succeeds at once. assert_eq!(start.elapsed(), 2 * BLUEZ_ASYNC_WAIT); assert_eq!( fake.calls(), @@ -1734,56 +1881,78 @@ mod bluez_discovery_tests { /// A discovery that never finishes fails as a "discover services" timeout /// `MIN_WAIT` after bluez-async gave up, even with a shorter - /// `discovery_timeout`, and disconnects. + /// `discovery_timeout`, and disconnects. The wait makes one re-ask: + /// bluez-async waits 30 s on it, longer than the 20 s the wait has. #[tokio::test(start_paused = true)] async fn gives_up_after_the_minimum_wait_and_disconnects() { within(Duration::from_secs(600), async { let fake = FakeGatt::new(); fake.script_connect(std::iter::repeat_with(|| Outcome::DiscoveryTimedOut).take(10)); - let config = ConnectionConfig::default().discovery_timeout(Duration::from_secs(5)); + let config = ConnectionConfig::default() + .connection_timeout(LONG_CONNECT_LIMIT) + .discovery_timeout(Duration::from_secs(5)); let start = Instant::now(); let result = connect_with(&fake, &config).await; assert_discovery_timeout(result, MIN_WAIT); + // The library gives up at 30 s. The wait ends at 50 s (30 + 20), + // before the re-ask's own 30 s are over (60 s). assert_eq!(start.elapsed(), BLUEZ_ASYNC_WAIT + MIN_WAIT); - let calls = fake.calls(); - assert_eq!(calls.last(), Some(&Call::Disconnect), "calls: {calls:?}"); - assert!(!calls.contains(&Call::Discover), "calls: {calls:?}"); - let connects = calls.iter().filter(|call| **call == Call::Connect).count(); - assert!(connects >= 5, "calls: {calls:?}"); + assert_eq!( + fake.calls(), + [Call::Connect, Call::Connect, Call::Disconnect] + ); }) .await; } - /// A `discovery_timeout` longer than `MIN_WAIT` lengthens the wait. + /// A `discovery_timeout` longer than `MIN_WAIT` lengthens the wait. With + /// 40 s the wait ends between two of bluez-async's 30 s rounds, so the + /// end of the wait and the end of a round can't be mistaken for each + /// other. #[tokio::test(start_paused = true)] async fn a_longer_discovery_timeout_waits_longer() { within(Duration::from_secs(600), async { let fake = FakeGatt::new(); fake.script_connect(std::iter::repeat_with(|| Outcome::DiscoveryTimedOut).take(10)); - let config = ConnectionConfig::challenging_environment(); + let config = ConnectionConfig::default() + .connection_timeout(Duration::from_secs(90)) + .discovery_timeout(Duration::from_secs(40)); let start = Instant::now(); let result = connect_with(&fake, &config).await; - assert_discovery_timeout(result, Duration::from_secs(30)); - assert_eq!(start.elapsed(), BLUEZ_ASYNC_WAIT + Duration::from_secs(30)); - assert_eq!(fake.calls().last(), Some(&Call::Disconnect)); + assert_discovery_timeout(result, Duration::from_secs(40)); + // The library gives up at 30 s and the wait ends at 70 s + // (30 + 40). The first re-ask gives up at 60 s; the second would + // at 90 s. + assert_eq!(start.elapsed(), BLUEZ_ASYNC_WAIT + Duration::from_secs(40)); + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::Connect, + Call::Connect, + Call::Disconnect, + ] + ); }) .await; } - /// Any other error ends the wait at once and fails the connect: here the - /// link dropped and BlueZ's new connection attempt failed. + /// Any other error ends the wait at once and fails the connect: here + /// bluez-async gave up under a long connect limit, the link had dropped, + /// and BlueZ's new connection attempt failed. #[tokio::test(start_paused = true)] async fn another_error_ends_the_wait() { within(Duration::from_secs(600), async { let fake = FakeGatt::new(); fake.script_connect([Outcome::DiscoveryTimedOut, Outcome::Fail]); + let config = ConnectionConfig::default().connection_timeout(LONG_CONNECT_LIMIT); let start = Instant::now(); - let result = connect_with(&fake, &ConnectionConfig::default()).await; + let result = connect_with(&fake, &config).await; assert_eq!( fake.calls(), @@ -1796,24 +1965,65 @@ mod bluez_discovery_tests { ), "got {result:?}" ); + // The library gives up at 30 s and the re-ask fails at once. assert_eq!(start.elapsed(), BLUEZ_ASYNC_WAIT); }) .await; } - /// The reconnect of the zero-services retry waits for BlueZ too. + /// The same at the default limits, where the wait starts at the connect's + /// own time limit: any other error from the re-ask ends the wait at once + /// and fails the connect. + #[tokio::test(start_paused = true)] + async fn another_error_ends_the_wait_after_a_connect_timeout() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([Outcome::Hang, Outcome::Fail]); + let config = ConnectionConfig::default(); + let start = Instant::now(); + + let result = connect_with(&fake, &config).await; + + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Disconnect, + ] + ); + assert!( + matches!( + result, + Err(Error::Bluetooth(btleplug::Error::RuntimeError(_))) + ), + "got {result:?}" + ); + // The connect's limit ends at 15 s and the re-ask fails at once. + assert_eq!(start.elapsed(), config.connection_timeout); + }) + .await; + } + + /// The reconnect of the zero-services retry waits for BlueZ too: here + /// after bluez-async gave up on it, under a long connect limit. #[tokio::test(start_paused = true)] async fn the_zero_services_retry_waits_too() { within(Duration::from_secs(600), async { let fake = FakeGatt::new(); fake.service_rounds([BTreeSet::new()]); fake.script_connect([Outcome::Ok, Outcome::DiscoveryTimedOut, Outcome::Ok]); + let config = ConnectionConfig::default().connection_timeout(LONG_CONNECT_LIMIT); let start = Instant::now(); - connect_with(&fake, &ConnectionConfig::default()) + connect_with(&fake, &config) .await .expect("the retry should wait for BlueZ's service discovery"); + // The retry's 2 s pause, then the library gives up 30 s into the + // reconnect and the re-ask succeeds at once: 32 s. assert_eq!(start.elapsed(), Duration::from_secs(2) + BLUEZ_ASYNC_WAIT); assert_eq!( fake.calls(), @@ -1830,32 +2040,67 @@ mod bluez_discovery_tests { .await; } - /// On BlueZ, a connect that runs out of time after the link came up, too - /// late for bluez-async's 5 s wait for the services to run out first, - /// waits for BlueZ's service discovery in the same way. The wait's limit - /// starts when the connect's ends and also covers the connection-state - /// query, which answers at once here, so the wait and the discovery get - /// all of it. + /// The same at the default limits: the retry's reconnect runs out of time + /// with the link up, the wait asks again, and BlueZ resolves the services + /// 4 s into the wait. #[tokio::test(start_paused = true)] - async fn a_connect_timeout_with_the_link_up_waits_on_bluez() { + async fn the_zero_services_retry_connects_after_a_connect_timeout() { within(Duration::from_secs(600), async { let fake = FakeGatt::new(); fake.set_bluez(true); + fake.service_rounds([BTreeSet::new()]); fake.script_connect([ + Outcome::Ok, Outcome::Hang, - Outcome::DiscoveryTimedOut, - Outcome::DiscoveryTimedOut, - Outcome::DiscoveryTimedOut, Outcome::After(Duration::from_secs(4)), ]); let config = ConnectionConfig::default(); let start = Instant::now(); + connect_with(&fake, &config) + .await + .expect("the retry should wait for BlueZ's service discovery"); + + // 2 s pause + 15 s connect limit + 4 s into the wait = 21 s. + assert_eq!(start.elapsed(), Duration::from_secs(21)); + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::Discover, + Call::Disconnect, + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Discover, + ] + ); + }) + .await; + } + + /// On BlueZ at the default limits, a connect whose discovery outlasts the + /// connect's 15 s runs out of time with the link up: bluez-async is still + /// inside its own 30 s wait for the services then. The connect waits for + /// BlueZ's service discovery by asking again. The wait's limit starts + /// when the connect's ends and also covers the connection-state query, + /// which answers at once here, so the wait and the discovery get all of + /// it: BlueZ may take 19 of its 20 s. + #[tokio::test(start_paused = true)] + async fn a_connect_timeout_with_the_link_up_waits_on_bluez() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([Outcome::Hang, Outcome::After(Duration::from_secs(19))]); + let config = ConnectionConfig::default(); + let start = Instant::now(); + connect_with(&fake, &config) .await .expect("the connect should wait for BlueZ's service discovery"); - // BlueZ resolves the services 19 s into the wait: 1 s inside it. + // BlueZ resolves the services 19 s into the wait: 1 s inside it + // (15 + 19 = 34 s). assert_eq!( start.elapsed(), config.connection_timeout + MIN_WAIT - Duration::from_secs(1) @@ -1866,9 +2111,6 @@ mod bluez_discovery_tests { Call::Connect, Call::IsConnected, Call::Connect, - Call::Connect, - Call::Connect, - Call::Connect, Call::Discover, ] ); @@ -1877,7 +2119,11 @@ mod bluez_discovery_tests { } /// On BlueZ, when that wait never ends, the connect fails as a "discover - /// services" timeout after the wait's limit, and disconnects. + /// services" timeout after the wait's limit, and disconnects. The wait + /// makes one re-ask, which is still inside bluez-async's 30 s when the + /// wait's 20 s are over. This is also how a link ends that BlueZ still + /// reports as connected after it has died: the connection check passes, + /// and no re-ask ever finds the services. #[tokio::test(start_paused = true)] async fn a_connect_timeout_with_the_link_up_gives_up_after_the_wait() { within(Duration::from_secs(600), async { @@ -1891,22 +2137,29 @@ mod bluez_discovery_tests { let result = connect_with(&fake, &config).await; assert_discovery_timeout(result, MIN_WAIT); + // The connect's limit ends at 15 s and the wait at 35 s + // (15 + 20). The re-ask's own 30 s would last until 45 s. assert_eq!(start.elapsed(), config.connection_timeout + MIN_WAIT); - let calls = fake.calls(); assert_eq!( - calls[..3], - [Call::Connect, Call::IsConnected, Call::Connect], - "calls: {calls:?}" + fake.calls(), + [ + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Disconnect, + ] ); - assert_eq!(calls.last(), Some(&Call::Disconnect), "calls: {calls:?}"); - assert!(!calls.contains(&Call::Discover), "calls: {calls:?}"); }) .await; } /// On BlueZ, a connect that runs out of time with the link down fails as /// before, with the "connect to device" timeout, and disconnects without - /// waiting. + /// waiting. The link may never have come up, or it came up and dropped + /// while bluez-async was still waiting for the services: bluez-async + /// does not watch the link during that wait (bluez-async 0.9.0 + /// `src/lib.rs:711-726`). Neither case is asked again inside the + /// connect. #[tokio::test(start_paused = true)] async fn a_connect_timeout_with_the_link_down_fails_on_bluez() { within(Duration::from_secs(600), async { @@ -2061,7 +2314,8 @@ mod bluez_discovery_tests { /// refuses the wait's first re-asks with `In Progress` until it has /// answered the timed-out `Device1.Connect`, which it does once the ATT /// channel is up. The wait asks again after a pause each time, then waits - /// for the discovery as before. + /// for the discovery as before: here BlueZ takes another 5 s once it has + /// accepted a re-ask. #[tokio::test(start_paused = true)] async fn a_connect_timeout_waits_while_bluez_is_still_connecting() { within(Duration::from_secs(600), async { @@ -2072,8 +2326,7 @@ mod bluez_discovery_tests { Outcome::InProgress, Outcome::InProgress, Outcome::InProgress, - Outcome::DiscoveryTimedOut, - Outcome::Ok, + Outcome::After(Duration::from_secs(5)), ]); let config = ConnectionConfig::default(); let start = Instant::now(); @@ -2082,9 +2335,10 @@ mod bluez_discovery_tests { .await .expect("the connect should wait while BlueZ is still connecting"); + // 15 s connect limit + three 1 s pauses + 5 s = 23 s. assert_eq!( start.elapsed(), - config.connection_timeout + 3 * IN_PROGRESS_PAUSE + BLUEZ_ASYNC_WAIT + config.connection_timeout + 3 * IN_PROGRESS_PAUSE + Duration::from_secs(5) ); assert!(start.elapsed() <= config.connection_timeout + MIN_WAIT); assert_eq!( @@ -2096,7 +2350,6 @@ mod bluez_discovery_tests { Call::Connect, Call::Connect, Call::Connect, - Call::Connect, Call::Discover, ] ); @@ -2141,17 +2394,23 @@ mod bluez_discovery_tests { /// After bluez-async's own discovery timeout, BlueZ has answered /// `Device1.Connect`, so an `In Progress` comes from another connect to /// the device or a pairing of it, and ends the wait at once, as before. + /// This path needs a connect limit above bluez-async's 30 s wait. Under + /// the default limits every wait starts at the connect's own time limit, + /// and there `In Progress` is asked again + /// (`a_connect_timeout_gives_up_while_bluez_stays_in_progress`). #[tokio::test(start_paused = true)] async fn in_progress_ends_the_wait_after_bluez_async_gave_up() { within(Duration::from_secs(600), async { let fake = FakeGatt::new(); fake.set_bluez(true); fake.script_connect([Outcome::DiscoveryTimedOut, Outcome::InProgress]); + let config = ConnectionConfig::default().connection_timeout(LONG_CONNECT_LIMIT); let start = Instant::now(); - let result = connect_with(&fake, &ConnectionConfig::default()).await; + let result = connect_with(&fake, &config).await; assert_in_progress(result); + // The library gives up at 30 s and the re-ask is refused at once. assert_eq!(start.elapsed(), BLUEZ_ASYNC_WAIT); assert_eq!( fake.calls(), @@ -2179,6 +2438,239 @@ mod bluez_discovery_tests { }) .await; } + + /// The usual slow first connect on BlueZ at the default limits: BlueZ is + /// still discovering when the connect's 15 s end, the link is up, and + /// BlueZ resolves the services 8 s into the wait. The connect succeeds + /// with one connection-state query and one re-ask. + #[tokio::test(start_paused = true)] + async fn a_discovery_that_outlasts_the_connect_limit_connects_through_the_wait() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([Outcome::Hang, Outcome::After(Duration::from_secs(8))]); + let config = ConnectionConfig::default(); + let start = Instant::now(); + + connect_with(&fake, &config) + .await + .expect("the connect should wait for BlueZ's service discovery"); + + // 15 s connect limit + 8 s into the wait = 23 s. + assert_eq!(start.elapsed(), Duration::from_secs(23)); + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Discover, + ] + ); + }) + .await; + } + + /// `aranet watch` connects with a 30 s limit by default. There a + /// discovery that takes 20 s finishes inside bluez-async's own wait for + /// the services, so the connect succeeds without a connection-state + /// query or a re-ask. + #[tokio::test(start_paused = true)] + async fn a_slow_discovery_inside_a_30_s_connect_limit_needs_no_wait() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([Outcome::After(Duration::from_secs(20))]); + let config = ConnectionConfig::default().connection_timeout(Duration::from_secs(30)); + let start = Instant::now(); + + connect_with(&fake, &config) + .await + .expect("bluez-async's own wait should cover the discovery"); + + // The one connect returns at 20 s, inside the 30 s limit. + assert_eq!(start.elapsed(), Duration::from_secs(20)); + assert_eq!(fake.calls(), [Call::Connect, Call::Discover]); + }) + .await; + } + + /// At `aranet watch`'s 30 s limit too, a connect that runs out of time + /// with the link down fails with its own timeout and is not asked again + /// inside the connect. That covers a link that came up and dropped while + /// bluez-async was waiting for the services: under a limit of 30 s or + /// less nothing re-dials it inside the connect. A caller that retries, + /// as `aranet watch` and the service do, dials again with its next + /// attempt. `aranet read` and the other one-shot commands do not retry: + /// for them the command fails with the connect's timeout. + #[tokio::test(start_paused = true)] + async fn a_30_s_connect_timeout_with_the_link_down_is_not_asked_again() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.set_connected(false); + fake.script_connect([Outcome::Hang]); + let config = ConnectionConfig::default().connection_timeout(Duration::from_secs(30)); + let start = Instant::now(); + + let error = connect_with(&fake, &config) + .await + .expect_err("the connect should fail"); + + assert_timeout(&error, "connect to device", Duration::from_secs(30)); + // The connect's limit ends at 30 s; the query finds the link down. + assert_eq!(start.elapsed(), Duration::from_secs(30)); + assert_eq!( + fake.calls(), + [Call::Connect, Call::IsConnected, Call::Disconnect] + ); + }) + .await; + } + + /// Under a connect limit longer than bluez-async's wait + /// (`ConnectionConfig::challenging_environment()`: a 90 s connect limit + /// and a 30 s `discovery_timeout`), bluez-async gives up first, 30 s in. + /// The wait asks again, and BlueZ resolves the services 6 s later. No + /// connection-state query is made: bluez-async's timeout itself shows + /// that BlueZ had answered `Device1.Connect` (bluez-async 0.9.0 + /// `src/lib.rs:759-760`). Under such a limit this is also how a link + /// that dropped during bluez-async's wait is dialled again: the re-ask + /// makes BlueZ open a new one. + #[tokio::test(start_paused = true)] + async fn bluez_async_gives_up_first_under_a_long_connect_limit() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([ + Outcome::DiscoveryTimedOut, + Outcome::After(Duration::from_secs(6)), + ]); + let config = ConnectionConfig::challenging_environment(); + let start = Instant::now(); + + connect_with(&fake, &config) + .await + .expect("the connect should wait for BlueZ's service discovery"); + + // The library gives up at 30 s; the re-ask succeeds 6 s later. + assert_eq!(start.elapsed(), BLUEZ_ASYNC_WAIT + Duration::from_secs(6)); + assert_eq!(fake.calls(), [Call::Connect, Call::Connect, Call::Discover]); + }) + .await; + } + + /// bluez-async gives the `Device1.Connect` call 30 s (bluez-async 0.9.0 + /// `src/lib.rs:57`, `:748-751`). When BlueZ sends no reply to + /// `Device1.Connect` in that time, a connect whose own limit is longer + /// fails with bluez-async's error, "Timeout waiting for reply". That is + /// not a timeout of the connect itself, so no connection-state query is + /// made and no wait starts: the connect disconnects and returns the + /// error. + #[tokio::test(start_paused = true)] + async fn a_dbus_reply_timeout_fails_the_connect_without_a_wait() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([Outcome::DbusTimeout]); + let config = ConnectionConfig::challenging_environment(); + let start = Instant::now(); + + let result = connect_with(&fake, &config).await; + + match result { + Err(Error::Bluetooth(btleplug::Error::Other(e))) => { + assert_eq!(e.to_string(), "Timeout waiting for reply"); + } + other => panic!("expected the D-Bus reply timeout, got {other:?}"), + } + // The D-Bus call's limit ends at 30 s, inside the 90 s connect + // limit. + assert_eq!(start.elapsed(), BLUEZ_DBUS_TIMEOUT); + assert_eq!(fake.calls(), [Call::Connect, Call::Disconnect]); + }) + .await; + } + + /// A guard on the fake. bluez-async waits 30 s for the services, so at + /// the default 15 s connect limit its "Service discovery timed out" can + /// never arrive before the connect's own limit ends. This script would + /// let it: with `BLUEZ_ASYNC_WAIT` at the default connect limit or below, + /// the library's timeout would start the wait, with no connection-state + /// query, and the test fails. With the wait at 30 s the connect's limit + /// ends the first call and the scripted timeout is never seen. + #[tokio::test(start_paused = true)] + async fn bluez_async_cannot_give_up_first_at_the_default_connect_limit() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.script_connect([ + Outcome::DiscoveryTimedOut, + Outcome::After(Duration::from_secs(2)), + ]); + let config = ConnectionConfig::default(); + let start = Instant::now(); + + connect_with(&fake, &config) + .await + .expect("the connect should wait for BlueZ's service discovery"); + + // 15 s connect limit + 2 s into the wait = 17 s. The scripted + // library timeout would have come at 30 s. + assert_eq!(start.elapsed(), Duration::from_secs(17)); + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Discover, + ] + ); + }) + .await; + } + + /// A discovery that stalls is ended by BlueZ itself: BlueZ 5.82 gives an + /// ATT request 30 s (`src/shared/att.c`, `ATT_TIMEOUT_INTERVAL`), then + /// shuts the channel down and marks the services as resolved although it + /// found none. A connect at the default limits waits up to 35 s in all + /// (15 s to its own limit, then a 20 s wait), so it can still be waiting + /// at that moment. Then the re-ask returns, the discovery finds no + /// services, and the connect goes into the zero-services retry. Here the + /// retry's fresh connection finds them. + #[tokio::test(start_paused = true)] + async fn a_discovery_that_bluez_ends_with_no_services_goes_into_the_retry() { + within(Duration::from_secs(600), async { + let fake = FakeGatt::new(); + fake.set_bluez(true); + fake.service_rounds([BTreeSet::new()]); + fake.script_connect([Outcome::Hang, Outcome::After(Duration::from_secs(17))]); + let config = ConnectionConfig::default(); + let start = Instant::now(); + + connect_with(&fake, &config) + .await + .expect("the retry's connection should find the services"); + + // 15 s connect limit + 17 s into the wait (3 s inside it) + the + // retry's 2 s pause = 34 s. + assert_eq!(start.elapsed(), Duration::from_secs(34)); + assert_eq!( + fake.calls(), + [ + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Discover, + Call::Disconnect, + Call::Connect, + Call::Discover, + ] + ); + }) + .await; + } } #[cfg(test)] @@ -2283,8 +2775,9 @@ mod pairing_tests { /// `Duration::MAX` is how a caller says "no limit". A connect must not /// panic on it: not when the pairing budget adds two of them, and not on /// BlueZ when the wait for BlueZ's service discovery starts with a - /// deadline `discovery_timeout` away, after bluez-async gave up waiting - /// for the services or after a connect timeout. + /// deadline `discovery_timeout` away. The wait starts after bluez-async + /// gave up waiting for the services, which a connect without a limit + /// lets it do after its 30 s, or after a finite connect limit ran out. #[tokio::test(start_paused = true)] async fn connect_with_unlimited_timeouts_does_not_panic() { within(Duration::from_secs(600), async { @@ -2302,8 +2795,9 @@ mod pairing_tests { [Call::Pair(Duration::MAX), Call::Connect, Call::Discover] ); - // On BlueZ, bluez-async gives up waiting for the services, so the - // connect waits for BlueZ to finish. + // On BlueZ, a connect without a limit lasts until bluez-async + // gives up waiting for the services, 30 s in (the fake's + // `BLUEZ_ASYNC_WAIT`), so the connect waits for BlueZ to finish. let bluez = FakeGatt::new(); bluez.set_bluez(true); bluez.script_pair([Outcome::Ok]); @@ -2396,4 +2890,39 @@ mod pairing_tests { }) .await; } + + /// Pairing, then the usual slow first connect on BlueZ: the pairing step + /// uses its whole 35 s budget, the connect after it runs out of its 15 s + /// with the link up, and BlueZ resolves the services 10 s into the wait. + /// The connect's limit and the wait start only when the pairing step has + /// returned. + #[tokio::test(start_paused = true)] + async fn pairing_then_a_discovery_that_outlasts_the_connect_limit_connects() { + within(Duration::from_secs(600), async { + let link = FakeGatt::new(); + link.set_bluez(true); + link.script_pair([Outcome::After(DEFAULT_BUDGET)]); + link.script_connect([Outcome::Hang, Outcome::After(Duration::from_secs(10))]); + let start = Instant::now(); + + connect_with(&link, &ConnectionConfig::default()) + .await + .expect("the connect should wait for BlueZ's service discovery"); + + // 35 s of pairing + 15 s connect limit + 10 s into the wait + // = 60 s. + assert_eq!(start.elapsed(), Duration::from_secs(60)); + assert_eq!( + link.calls(), + [ + Call::Pair(DEFAULT_BUDGET), + Call::Connect, + Call::IsConnected, + Call::Connect, + Call::Discover, + ] + ); + }) + .await; + } } diff --git a/crates/aranet-core/src/link/fake.rs b/crates/aranet-core/src/link/fake.rs index 568cfeb..13630dd 100644 --- a/crates/aranet-core/src/link/fake.rs +++ b/crates/aranet-core/src/link/fake.rs @@ -20,27 +20,66 @@ pub(super) enum Outcome { /// Fail at once with a Bluetooth error, as a refused connection or a /// failed discovery does. Fail, - /// Never answer, as btleplug does on macOS once CoreBluetooth has dropped - /// the peripheral. + /// Never answer. It stands for two things. One is a BlueZ `connect` that + /// is still waiting when aranet's own limit ends: bluez-async waits up to + /// 30 s for BlueZ's reply to `Device1.Connect` and then up to 30 s for the + /// services (bluez-async 0.9.0 `src/lib.rs:57`, `:61`), so under the 15 s + /// default limit this is how a slow first connect is scripted. The other + /// is a call that the stack never answers, such as a CoreBluetooth + /// connect to a sensor that has gone. Hang, /// Fail as bluez-async's `connect` does while BlueZ is still discovering /// the services of a connected device: after `BLUEZ_ASYNC_WAIT`, with - /// `btleplug::Error::Other("Service discovery timed out")`. + /// `btleplug::Error::Other("Service discovery timed out")`. The wait + /// starts at the call, as if BlueZ answered `Device1.Connect` at once, + /// which it does when a wait asks again on a live link. The caller sees + /// this outcome only if its own limit is `BLUEZ_ASYNC_WAIT` or longer; + /// that constant's doc says why a limit of exactly that length must be + /// scripted with `Hang`. DiscoveryTimedOut, /// Fail at once as BlueZ refuses a `Device1.Connect` while an earlier one /// to the same device is still pending (`org.bluez.Error.InProgress`), /// with `btleplug::Error::Other("In Progress")`. InProgress, + /// Fail as bluez-async's `connect` does when BlueZ sends no reply to + /// `Device1.Connect` within the D-Bus call's own limit: after + /// `BLUEZ_DBUS_TIMEOUT`, with + /// `btleplug::Error::Other("Timeout waiting for reply")`. A caller whose + /// own limit is shorter never sees it. + DbusTimeout, /// Wait this long on the tokio clock, then succeed like `Ok`. A /// `disconnect` that ends this way notifies `disconnected()` at the end - /// of the wait. + /// of the wait. As a BlueZ `connect` it stands for BlueZ resolving the + /// services that long after the call: bluez-async's `connect` can succeed + /// up to `BLUEZ_ASYNC_WAIT` after BlueZ's answer, which for a re-ask on a + /// live link comes at once. After(std::time::Duration), } /// How long bluez-async's `connect` waits for BlueZ's `ServicesResolved` -/// before it fails (`SERVICE_DISCOVERY_TIMEOUT`, bluez-async 0.8.2 -/// `src/lib.rs:61`). -pub(super) const BLUEZ_ASYNC_WAIT: std::time::Duration = std::time::Duration::from_secs(5); +/// before it fails (`SERVICE_DISCOVERY_TIMEOUT`, bluez-async 0.9.0 +/// `src/lib.rs:61`). It was 5 s before btleplug 0.13.5. +/// +/// Never script `Outcome::DiscoveryTimedOut` for a call whose own limit is +/// exactly 30 s: script `Outcome::Hang`. Such a call is a first connect or +/// the zero-services retry's reconnect under a 30 s `connection_timeout` +/// (`aranet watch`'s default), or a call made again in a wait that has +/// exactly 30 s left, as the first one can have under a 30 s +/// `discovery_timeout` (`ConnectionConfig::challenging_environment()`). +/// bluez-async starts this wait only once BlueZ has answered +/// `Device1.Connect`, so on a real host its timeout comes more than 30 s +/// after the call, and a limit of 30 s or less always ends first. This fake +/// starts the wait at the call. With a limit of exactly 30 s both would end +/// at the same instant of the paused clock, tokio's `timeout` and +/// `timeout_at` poll the call before their own timer, and the test would +/// see the library's timeout first: an order that cannot happen. Under a +/// shorter limit the fake keeps the real order. +pub(super) const BLUEZ_ASYNC_WAIT: std::time::Duration = std::time::Duration::from_secs(30); + +/// How long bluez-async waits for BlueZ's reply to a D-Bus method call, such +/// as the `Device1.Connect` that its `connect` starts with, before the call +/// fails (`DBUS_METHOD_CALL_TIMEOUT`, bluez-async 0.9.0 `src/lib.rs:57`). +pub(super) const BLUEZ_DBUS_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30); /// A call made on a `FakeGatt`, in the order it was made. #[derive(Debug, Clone, PartialEq, Eq)] @@ -97,6 +136,7 @@ impl State { // Sending fails only to a stream that has been dropped. let _ = stream.unbounded_send(ValueNotification { uuid, + service_uuid: SAF_TEHNIKA_SERVICE_NEW, value: value.to_vec(), }); } @@ -246,13 +286,20 @@ async fn run(outcome: Option) -> btleplug::Result<()> { Outcome::DiscoveryTimedOut => { tokio::time::sleep(BLUEZ_ASYNC_WAIT).await; // bluez-async's `BluetoothError::ServiceDiscoveryTimedOut` - // (`src/lib.rs:90-92`), which btleplug wraps in `Error::Other` - // (`src/bluez/adapter.rs:125-129`). + // (bluez-async 0.9.0 `src/lib.rs:90-92`), which btleplug wraps in + // `Error::Other` (btleplug 0.13.5 `src/bluez/adapter.rs:182-186`). Err(btleplug::Error::Other("Service discovery timed out".into())) } // bluez-async's `BluetoothError::DbusError`, whose text is the D-Bus // error's message, wrapped in `Error::Other` by btleplug. Outcome::InProgress => Err(btleplug::Error::Other("In Progress".into())), + Outcome::DbusTimeout => { + tokio::time::sleep(BLUEZ_DBUS_TIMEOUT).await; + // The same kind of error: the D-Bus call ran out of time, and + // this is the message it fails with (dbus 0.9.12 + // `src/nonblock.rs:512`). + Err(btleplug::Error::Other("Timeout waiting for reply".into())) + } Outcome::After(delay) => { tokio::time::sleep(delay).await; Ok(()) @@ -301,8 +348,12 @@ impl GattLink for FakeGatt { async fn properties(&self) -> btleplug::Result> { let outcome = self.lock().properties.pop_front(); run(outcome).await?; + // Both name fields hold the advertised name, as btleplug 0.13.5 reports + // a named sensor on BlueZ while no alias is set, on CoreBluetooth once + // a name has been advertised, and on WinRT before a connect. Ok(Some(PeripheralProperties { local_name: Some("Aranet4 12345".to_string()), + advertisement_name: Some("Aranet4 12345".to_string()), ..Default::default() })) } diff --git a/crates/aranet-core/src/manager.rs b/crates/aranet-core/src/manager.rs index c5057e7..48e5279 100644 --- a/crates/aranet-core/src/manager.rs +++ b/crates/aranet-core/src/manager.rs @@ -883,9 +883,9 @@ impl ManagerCore { }; // The link has left the manager: say so before the close, as `detach` - // does. The close can fail (on macOS, closing a link that dropped on - // its own times out) or go on in the background if this future is - // dropped, and nothing would send the event later. + // does. The close can fail (it gives up when the Bluetooth stack + // doesn't confirm the disconnect in time) or go on in the background + // if this future is dropped, and nothing would send the event later. self.events.send(DeviceEvent::Disconnected { device: DeviceId::new(identifier), reason: DisconnectReason::UserRequested, @@ -2696,10 +2696,10 @@ mod lifecycle_tests { } /// A disconnect sends `Disconnected` once it has taken the link out of - /// the manager, even if closing the link then fails (as closing a link - /// that dropped on its own does on macOS): the manager reports the device - /// as disconnected from then on, and nothing sends the event later. The - /// error is still returned. + /// the manager, even if closing the link then fails (as it does when the + /// Bluetooth stack doesn't confirm the disconnect in time): the manager + /// reports the device as disconnected from then on, and nothing sends + /// the event later. The error is still returned. #[tokio::test(start_paused = true)] async fn disconnects_send_disconnected_even_if_the_close_fails() { within(TEST_LIMIT, async { diff --git a/crates/aranet-core/src/pairing.rs b/crates/aranet-core/src/pairing.rs index 2755eab..ceca9ca 100644 --- a/crates/aranet-core/src/pairing.rs +++ b/crates/aranet-core/src/pairing.rs @@ -53,7 +53,7 @@ //! battery plugin reads the Battery Level, which needs encryption) and finds //! no agent on a headless host, so after a timeout or a lost link the next //! connect pairs again. -//! - btleplug 0.11.8 has no pairing call. +//! - btleplug 0.13.5 has no pairing call. use std::collections::HashMap; use std::fmt; diff --git a/crates/aranet-core/src/passive.rs b/crates/aranet-core/src/passive.rs index cfd255d..4221f16 100644 --- a/crates/aranet-core/src/passive.rs +++ b/crates/aranet-core/src/passive.rs @@ -46,6 +46,7 @@ use tracing::{debug, info, warn}; use crate::advertisement::{AdvertisementData, parse_advertisement_with_name}; use crate::error::Result; use crate::scan::get_adapter; +use crate::util::peripheral_name; use crate::uuid::MANUFACTURER_ID; /// Bitwise-exact comparison of two `Option` values (handles NaN correctly). @@ -296,7 +297,7 @@ impl PassiveMonitor { } // Try to parse the advertisement - match parse_advertisement_with_name(data, props.local_name.as_deref()) { + match parse_advertisement_with_name(data, peripheral_name(&props)) { Ok(adv_data) => { // Check for deduplication let should_emit = if self.options.deduplicate { @@ -308,7 +309,7 @@ impl PassiveMonitor { if should_emit { let reading = PassiveReading { device_id: device_id.clone(), - device_name: props.local_name.clone(), + device_name: peripheral_name(&props).map(str::to_owned), rssi: props.rssi, data: adv_data.clone(), received_at: std::time::Instant::now(), diff --git a/crates/aranet-core/src/scan.rs b/crates/aranet-core/src/scan.rs index 747c0a6..77b59c6 100644 --- a/crates/aranet-core/src/scan.rs +++ b/crates/aranet-core/src/scan.rs @@ -63,7 +63,7 @@ async fn reset_manager() { } use crate::error::{Error, Result}; -use crate::util::create_identifier; +use crate::util::{create_identifier, peripheral_name}; use crate::uuid::{MANUFACTURER_ID, SAF_TEHNIKA_SERVICE_NEW, SAF_TEHNIKA_SERVICE_OLD}; use aranet_types::DeviceType; @@ -241,11 +241,16 @@ async fn cached_adapter() -> Result { /// Whether the cached adapter's CoreBluetooth thread still takes requests. /// -/// btleplug's CoreBluetooth thread can panic (for example when services are -/// discovered after a connect has timed out). Every later request on that -/// adapter then fails with "Channel closed", so it has to be replaced. A reply -/// that is merely slow keeps the adapter: only a closed channel proves the -/// thread is gone. +/// btleplug's CoreBluetooth thread runs a loop that never returns (btleplug +/// 0.13.5 `src/corebluetooth/internal.rs:2030-2038`), so it stops only if it +/// panics. btleplug 0.11.8 panicked on a discovery callback that came late, +/// for a service it no longer knew or with no connect waiting; 0.13.5 +/// ignores those (`:397-400`, `:534-538`). This check stays as a guard +/// against any other panic: every later request on an adapter whose thread +/// has stopped fails with "Channel closed" +/// (`src/corebluetooth/peripheral.rs:678-682`), so the adapter has to be +/// replaced. A reply that is merely slow keeps the adapter: only a closed +/// channel proves the thread is gone. async fn adapter_thread_is_running(adapter: &Adapter) -> bool { let adapter = adapter.clone(); // Run on aranet-core's runtime so the timeout works even if the caller's @@ -532,7 +537,7 @@ async fn process_peripheral( let id = peripheral.id(); let address = properties.address.to_string(); - let name = properties.local_name.clone(); + let name = peripheral_name(&properties).map(str::to_owned); let rssi = properties.rssi; // Check if this is an Aranet device @@ -586,7 +591,7 @@ fn is_aranet_device(properties: &btleplug::api::PeripheralProperties) -> bool { } // Check device name for Aranet - if let Some(name) = &properties.local_name { + if let Some(name) = peripheral_name(properties) { let name_lower = name.to_lowercase(); if name_lower.contains("aranet") { return true; @@ -606,24 +611,37 @@ fn aranet_service_filter() -> ScanFilter { /// Whether every scan window of a device search asks the Bluetooth stack only for /// devices that advertise an Aranet service (see `search_filter`). Only on macOS: -/// btleplug's CoreBluetooth backend keeps every device a scan reports for the -/// rest of the process and leaks a little memory for every advertisement it -/// receives, so unfiltered searches near many Bluetooth devices make a -/// long-running program grow by 1-2 MB an hour. Leaving only a search's last -/// window unfiltered wasn't enough: in a 12 h macOS soak, the 8.5% of the -/// service's polls whose search reached that window added about 106 kB each -/// (about 80% of the growth, against about 2 kB for a search that ended -/// earlier), and a sensor out of range runs it on every poll, about 6 MB an hour. +/// btleplug's CoreBluetooth backend keeps every device a scan reports (its +/// `CBPeripheral`, an entry in the adapter's list and a task of its own) until +/// the device disconnects after a connection, Bluetooth is switched off or +/// `clear_peripherals()` is called (btleplug 0.13.5 +/// `src/corebluetooth/internal.rs:1010-1013`; removed at `:1175`, `:1153` and +/// `:1924`). aranet never calls `clear_peripherals()` and shares one adapter for +/// the life of the process, so a device that is only scanned stays until +/// Bluetooth is switched off or the process ends. With the filter, a device +/// search adds only Aranet sensors to that list. +/// +/// The filter was added on btleplug 0.11.8, which also leaked a little memory +/// for every advertisement it received, and the figures here were measured on +/// it. Unfiltered searches near many Bluetooth devices made a long-running +/// program grow by 1-2 MB an hour. Leaving only a search's last window +/// unfiltered wasn't enough: in a 12 h macOS soak, the 8.5% of the service's +/// polls whose search reached that window added about 106 kB each (about 80% of +/// the growth, against about 2 kB for a search that ended earlier), and a +/// sensor out of range ran it on every poll, about 6 MB an hour. +/// +/// btleplug 0.13.5 drains an autorelease pool for every message on its +/// CoreBluetooth thread (`src/corebluetooth/internal.rs:1990-2014`, +/// `:2034-2036`), which by its source ends the growth per advertisement +/// (). That has not been +/// measured, and the list of kept devices is as it was, so the filter stays +/// unchanged until a memory measurement on 0.13.5 says otherwise. /// /// The cost: a macOS search doesn't find a sensor that advertises neither Aranet /// service UUID. All four current Aranet sensor types advertise 0xFCE0; older /// firmware is untested. `aranet scan`, `scan_with_options` and the passive /// monitor still see every device. Linux and Windows searches ask for every /// device. -/// -/// Workaround for btleplug 0.11.8 -/// (); re-check when -/// upgrading btleplug. const FILTER_SEARCH_WINDOWS: bool = cfg!(target_os = "macos"); /// The scan filter of every window of a device search: with `aranet_only`, it @@ -678,8 +696,8 @@ fn after_missed_scan( /// - btleplug's device ID as [`DiscoveredDevice::id`] displays it /// (`hci0/dev_AA_BB_CC_DD_EE_FF` on Linux); /// - the MAC address, with or without colons; -/// - the whole advertised name. On macOS a name shown as -/// `"Kitchen [Aranet4 1A2B3]"` also matches `Kitchen` or `Aranet4 1A2B3`. +/// - the device's whole name, as [`peripheral_name`] gives it and +/// [`DiscoveredDevice::name`] holds it. /// /// An address or identifier match wins over a name match. /// @@ -879,7 +897,9 @@ struct KnownPeripheral { peripheral_id: String, /// The Bluetooth address; `00:00:00:00:00:00` on macOS. address: String, - /// The advertised name. + /// The device's name as `peripheral_name` gives it: the advertised name, + /// or on macOS CoreBluetooth's own name for a peripheral that advertised + /// none. name: Option, } @@ -913,9 +933,12 @@ fn parse_query(identifier: &str) -> Result<&str> { /// 1. an identifier: the one `aranet scan` prints, btleplug's device ID (the /// `hci0/dev_…` form on Linux), or the Bluetooth address with or without /// colons, never `00:00:00:00:00:00`; -/// 2. the whole advertised name, or either half of CoreBluetooth's combined -/// `" []"` (btleplug 0.11.8, -/// `corebluetooth/internal.rs:577-585`). +/// 2. the whole name, ignoring the spaces around it. Part of a name never +/// matches, and that includes a name with a bracketed part: btleplug +/// 0.11.8 named some macOS peripherals +/// `" []"`, and 0.13.5 never builds that +/// form (`src/corebluetooth/internal.rs:1003-1008`, +/// `src/corebluetooth/peripheral.rs:221-235`). /// /// One match is `Found` and several are `Ambiguous`. With no match, `NotFound` /// lists the peripherals whose name contains both `query` and `aranet`, so a @@ -973,15 +996,10 @@ fn decide(indices: Vec) -> Option { } } -/// Whether the advertised `name` is `query` (lower case): the whole name, or -/// either half of CoreBluetooth's `" []"`. +/// Whether `name` is `query` (lower case): the whole name, ignoring case and +/// the spaces around it. fn name_matches(name: &str, query: &str) -> bool { - let name = name.trim().to_lowercase(); - name == query - || name - .strip_suffix(']') - .and_then(|combined| combined.rsplit_once(" [")) - .is_some_and(|(gap, advertised)| gap.trim() == query || advertised.trim() == query) + name.trim().to_lowercase() == query } /// What a search of the known peripherals found. @@ -1046,7 +1064,7 @@ async fn search_known_peripherals(adapter: &Adapter, query: &str) -> Result btleplug::api::PeripheralProperties { + btleplug::api::PeripheralProperties { + local_name: Some(local_name.to_string()), + advertisement_name: Some(advertisement_name.to_string()), + ..Default::default() + } + } + + #[test] + fn is_aranet_device_recognises_a_sensor_by_its_name_alone() { + // No manufacturer data and no service: the name is all there is. Both + // fields hold it, as btleplug 0.13.5 reports a named sensor on BlueZ + // while no alias is set, on CoreBluetooth once a name has been + // advertised, and on WinRT before a connect, so the answer is the same + // on every host. + assert!(is_aranet_device(&named("Aranet4 12345", "Aranet4 12345"))); + assert!(is_aranet_device(&named("ARANET2 2751B", "ARANET2 2751B"))); + assert!(!is_aranet_device(&named("Standing desk", "Standing desk"))); + let unnamed = btleplug::api::PeripheralProperties::default(); + assert!(!is_aranet_device(&unnamed)); + } + + #[test] + fn is_aranet_device_takes_the_name_from_peripheral_name() { + // As BlueZ reports a sensor that the user has renamed: the first name + // is the alias, the second the sensor's own. + assert!(is_aranet_device(&named("Kitchen", "Aranet4 12345"))); + // A device that the user has named after a sensor is not one. + assert!(!is_aranet_device(&named("Aranet shelf", "Standing desk"))); + } + // ==================== Device Lookup Tests ==================== /// CoreBluetooth UUIDs as `aranet scan` prints them on macOS. The first two @@ -1789,17 +1841,35 @@ mod tests { } } + /// Only the whole name matches, also when the name has a bracketed part. + /// btleplug 0.11.8 named some macOS peripherals + /// `" []"`, and while aranet used it, each + /// half of such a name matched too. btleplug 0.13.5 never builds that form. #[test] - fn lookup_matches_either_half_of_a_corebluetooth_combined_name() { + fn lookup_matches_a_name_with_a_bracketed_part_only_as_a_whole() { let devices = [ on_macos(UUID_2, "AranetRn+ 306B8"), on_macos(UUID_1, "Kitchen [Aranet4 1A2B3]"), ]; - for query in ["Aranet4 1A2B3", "kitchen", "Kitchen [Aranet4 1A2B3]"] { - assert_eq!(lookup(query, &devices), Lookup::Found(1), "{query:?}"); + assert_eq!( + lookup("kitchen [aranet4 1a2b3]", &devices), + Lookup::Found(1) + ); + for half in ["Kitchen", "Aranet4 1A2B3"] { + assert_eq!( + lookup(half, &devices), + Lookup::NotFound { similar: vec![1] }, + "{half:?}" + ); } } + #[test] + fn lookup_ignores_spaces_around_a_device_name() { + let devices = [on_macos(UUID_1, " Aranet2 2751B ")]; + assert_eq!(lookup("aranet2 2751b", &devices), Lookup::Found(0)); + } + #[test] fn lookup_prefers_an_identifier_match_over_a_name_match() { let devices = [ @@ -1968,11 +2038,15 @@ mod tests { } // ==================== DiscoveredDevice Tests ==================== - // Note: DiscoveredDevice tests are removed because PeripheralId from btleplug - // has platform-specific implementations that cannot be easily mocked in tests. - // - macOS: PeripheralId wraps a UUID - // - Linux: PeripheralId wraps bluez_async::DeviceId (not directly accessible) - // - Windows: PeripheralId wraps a u64 + // Note: this module has no test that builds a DiscoveredDevice. Its `id` is + // btleplug's PeripheralId, which wraps a different type on each platform + // (btleplug 0.13.5): + // - macOS: PeripheralId wraps a UUID (`src/corebluetooth/peripheral.rs:46`) + // - Linux: PeripheralId wraps bluez_async::DeviceId + // (`src/bluez/peripheral.rs:49`). btleplug doesn't re-export bluez-async + // and aranet-core doesn't depend on it directly, so this crate can't name + // that type to make one + // - Windows: PeripheralId wraps a BDAddr (`src/winrtble/peripheral.rs:57`) // // The DiscoveredDevice struct derives Clone and Debug, so these traits are // guaranteed to work correctly by the compiler. diff --git a/crates/aranet-core/src/util.rs b/crates/aranet-core/src/util.rs index 008b9ff..f00ab70 100644 --- a/crates/aranet-core/src/util.rs +++ b/crates/aranet-core/src/util.rs @@ -2,6 +2,7 @@ //! //! This module contains shared utility functions used across the crate. +use btleplug::api::PeripheralProperties; use btleplug::platform::PeripheralId; /// Format a peripheral ID as a string. @@ -38,16 +39,99 @@ pub fn create_identifier(address: &str, peripheral_id: &PeripheralId) -> String } } +/// Whether a peripheral that has advertised no name is named by btleplug's +/// `local_name`. Only on macOS, where `local_name` is then CoreBluetooth's own +/// name for the peripheral (btleplug 0.13.5 +/// `src/corebluetooth/internal.rs:1003-1008`). On Linux it is then BlueZ's +/// `Alias` (`src/bluez/peripheral.rs:155`), which for a device BlueZ has no +/// name for is a name the user chose, or else the address with dashes. On +/// Windows a connect sets it to the system's name for the device +/// (`src/winrtble/peripheral.rs:523-531`). aranet has never used either as a +/// sensor's name. +const UNADVERTISED_NAME_IS_LOCAL_NAME: bool = cfg!(target_os = "macos"); + +/// The name of a peripheral as aranet uses it: the name aranet shows, matches +/// a device query against and detects the sensor type from. +/// +/// It is the name the device advertises, which btleplug reports as +/// `advertisement_name`. On macOS only, a peripheral that has advertised no +/// name gets the name CoreBluetooth holds for it, which btleplug reports as +/// `local_name`. +/// +/// Call this function and do not read either field yourself. +/// `advertisement_name` alone leaves a macOS peripheral that has advertised +/// no name without one. `local_name` means something different on each +/// operating system in btleplug 0.13.5 (the files named below are that +/// version's): +/// +/// - **Linux:** BlueZ's `Alias` (`src/bluez/peripheral.rs:155`): the name the +/// user gave the device, else the device's own name, else its address with +/// dashes, such as `60-C0-BF-48-CB-8D` (BlueZ 5.82 `src/device.c:959-980`). +/// Read as a name, it would take a renamed sensor's Aranet name away, and +/// with it the sensor type that is detected from the name, and it would +/// give a name to a device that has none. `advertisement_name` is BlueZ's +/// `Name` (`src/bluez/peripheral.rs:156`), which is what `local_name` was +/// in btleplug 0.11.8. +/// - **Windows:** the advertised name, until a connect replaces it with the +/// system's name for the device (`src/winrtble/peripheral.rs:523-531`). +/// `advertisement_name` is the name from the last advertisement that carried +/// one (`src/winrtble/peripheral.rs:173-180`), which is what `local_name` +/// was in btleplug 0.11.8. +/// - **macOS:** the advertised name once one has been heard, and until then +/// the name CoreBluetooth holds for the peripheral +/// (`src/corebluetooth/internal.rs:1003-1008`, +/// `src/corebluetooth/peripheral.rs:221-235`). On macOS this function +/// returns what `local_name` holds. +/// +/// # Example +/// +/// ``` +/// use aranet_core::peripheral_name; +/// use btleplug::api::PeripheralProperties; +/// +/// // A sensor as BlueZ reports it after the user has renamed it "Kitchen". +/// let properties = PeripheralProperties { +/// local_name: Some("Kitchen".to_string()), +/// advertisement_name: Some("Aranet4 12345".to_string()), +/// ..Default::default() +/// }; +/// assert_eq!(peripheral_name(&properties), Some("Aranet4 12345")); +/// ``` +pub fn peripheral_name(properties: &PeripheralProperties) -> Option<&str> { + name_from(properties, UNADVERTISED_NAME_IS_LOCAL_NAME) +} + +/// `peripheral_name` with the choice that depends on the operating system as a +/// parameter, so that one host can test every rule: the advertised name, or, +/// if there is none and `or_local_name` is set, `local_name`. +fn name_from(properties: &PeripheralProperties, or_local_name: bool) -> Option<&str> { + let advertised = properties.advertisement_name.as_deref(); + if or_local_name { + advertised.or(properties.local_name.as_deref()) + } else { + advertised + } +} + #[cfg(test)] mod tests { - // Note: We can't easily create PeripheralId in tests, so we test the logic - // rather than calling the functions directly. + // Note: `test_create_identifier_with_valid_address` and + // `test_create_identifier_with_zero_address` don't call `create_identifier` + // or `format_peripheral_id`. Both functions take btleplug's PeripheralId, + // and a test that runs on every platform can't make one. btleplug 0.13.5 + // makes one from a UUID on macOS (`src/corebluetooth/peripheral.rs:672`) + // and from a BDAddr on Windows (`src/winrtble/peripheral.rs:732`), but on + // Linux only from a bluez_async::DeviceId (`src/bluez/peripheral.rs:358`). + // aranet-core can't name that type: btleplug doesn't re-export bluez-async, + // and aranet-core doesn't depend on it directly. So the two tests only + // compare an address with the all-zero one, as `create_identifier` does. #[allow(unused_imports)] use super::*; #[test] fn test_create_identifier_with_valid_address() { - // We can't easily create a PeripheralId in tests, but we can test the logic + // No PeripheralId here (see the note on PeripheralId in this module), + // so this only compares the address with the all-zero one. let address = "AA:BB:CC:DD:EE:FF"; // When address is valid, it should be used directly assert_ne!(address, "00:00:00:00:00:00"); @@ -59,3 +143,196 @@ mod tests { assert_eq!(address, "00:00:00:00:00:00"); } } + +#[cfg(test)] +mod peripheral_name_tests { + use super::*; + + use std::path::{Path, PathBuf}; + + use aranet_types::DeviceType; + + /// What `name_from` is given on Linux and Windows. + const ADVERTISED_NAME_ONLY: bool = false; + /// What `name_from` is given on macOS. + const OR_LOCAL_NAME: bool = true; + + /// Properties that carry nothing but the two names. + fn named(local_name: Option<&str>, advertisement_name: Option<&str>) -> PeripheralProperties { + PeripheralProperties { + local_name: local_name.map(str::to_owned), + advertisement_name: advertisement_name.map(str::to_owned), + ..Default::default() + } + } + + #[test] + fn bluez_alias_does_not_replace_the_sensors_name() { + // BlueZ, for a sensor the user has renamed: `local_name` is the alias + // and `advertisement_name` is BlueZ's `Name`. + let properties = named(Some("Kitchen"), Some("Aranet2 2751B")); + let name = name_from(&properties, ADVERTISED_NAME_ONLY); + assert_eq!(name, Some("Aranet2 2751B")); + // The sensor type is detected from the name, and a sensor without a + // type is read and parsed as an Aranet4. + assert_eq!( + name.and_then(DeviceType::from_name), + Some(DeviceType::Aranet2) + ); + } + + #[test] + fn bluez_device_without_a_name_has_none() { + // BlueZ, for a device it has no name for: the alias is the address + // with dashes. + let properties = named(Some("60-C0-BF-48-CB-8D"), None); + assert_eq!(name_from(&properties, ADVERTISED_NAME_ONLY), None); + } + + #[test] + fn winrt_connect_does_not_change_the_name() { + // WinRT after a connect: `local_name` is the system's name for the + // device. + let connected = named(Some("Bedroom sensor"), Some("Aranet4 17C3C")); + assert_eq!( + name_from(&connected, ADVERTISED_NAME_ONLY), + Some("Aranet4 17C3C") + ); + // A device that never advertised a name stays without one. + let never_named = named(Some("Bedroom sensor"), None); + assert_eq!(name_from(&never_named, ADVERTISED_NAME_ONLY), None); + } + + #[test] + fn corebluetooth_uses_the_advertised_name() { + // CoreBluetooth once a name has been advertised: both fields hold it. + let properties = named(Some("Aranet4 1A2B3"), Some("Aranet4 1A2B3")); + assert_eq!(name_from(&properties, OR_LOCAL_NAME), Some("Aranet4 1A2B3")); + } + + #[test] + fn corebluetooth_falls_back_to_the_systems_name() { + // CoreBluetooth before any name has been advertised: `local_name` is + // its own name for the peripheral. + let properties = named(Some("Kitchen"), None); + assert_eq!(name_from(&properties, OR_LOCAL_NAME), Some("Kitchen")); + } + + #[test] + fn corebluetooth_peripheral_without_a_name_has_none() { + let properties = named(None, None); + assert_eq!(name_from(&properties, OR_LOCAL_NAME), None); + } + + #[test] + fn an_advertised_name_wins_over_local_name() { + // CoreBluetooth never reports two different names (btleplug 0.13.5 + // `src/corebluetooth/peripheral.rs:221-235`). This pins the order of + // the rule: `local_name` is used only when no name was advertised. + let properties = named(Some("Kitchen"), Some("Aranet2 2751B")); + assert_eq!(name_from(&properties, OR_LOCAL_NAME), Some("Aranet2 2751B")); + } + + /// The one test of `UNADVERTISED_NAME_IS_LOCAL_NAME`. Every other test + /// passes the rule to `name_from` itself, so without this one the constant + /// could be `true` on Linux, which makes a BlueZ alias a sensor's name + /// again, with every other test passing. CI runs it on macOS, Linux and + /// Windows. + #[test] + fn peripheral_name_uses_local_name_only_on_macos() { + let properties = named(Some("Kitchen"), None); + let expected = cfg!(target_os = "macos").then_some("Kitchen"); + assert_eq!(peripheral_name(&properties), expected); + } + + /// Every `.rs` file under `dir`, at any depth. + fn rust_files(dir: &Path, found: &mut Vec) { + for entry in std::fs::read_dir(dir).expect("read a source directory") { + let path = entry.expect("read a directory entry").path(); + if path.is_dir() { + rust_files(&path, found); + } else if path.extension().is_some_and(|extension| extension == "rs") { + found.push(path); + } + } + } + + /// Guard: in aranet-core only `name_from` (this file) reads btleplug's + /// `local_name` and `advertisement_name`. + /// + /// Six places in the crate need a peripheral's name: the scan + /// (`process_peripheral` and `is_aranet_device`), the device lookup + /// (`search_known_peripherals`), the connect + /// (`Device::from_peripheral_with_config`) and the passive monitor, twice. + /// Five of them take a real btleplug peripheral and cannot be unit-tested, + /// so no other test would notice if one of them read a field itself. A + /// site that read `local_name` would name a sensor on Linux by its BlueZ + /// alias, and the sensor would lose its type. A site that read + /// `advertisement_name` directly would pass every other test and lose the + /// system's name on macOS for a sensor that has not advertised one. + /// + /// So this test reads the source files. It fails on either field's name + /// after a dot, in code or in a comment, in any file but this one. A + /// struct literal that sets the fields has no dot before their names and + /// passes: the test double of a peripheral (`link/fake.rs`) sets them + /// that way. + /// + /// Two kinds of read get past it. A pattern that takes a field out of + /// the struct (`PeripheralProperties { local_name, .. }`) has no dot + /// before the name. And this file is skipped as a whole, so a second read + /// in it, outside `name_from`, passes too. There is neither today, and + /// only a review keeps it so. + /// + /// It searches `src` only. The `discover_services` example and the + /// hardware tests' `known_peripheral` take the name from `peripheral_name` + /// too, but they are outside `src`, and this test does not read them. + #[test] + fn only_peripheral_name_reads_the_name_fields() { + // Each in two halves, so that a text search of the crate for them + // finds only the two reads in `name_from`. The test itself does not + // need the split: it skips this file. + let field_reads = [ + [".local", "_name"].concat(), + [".advertisement", "_name"].concat(), + ]; + let src = Path::new(env!("CARGO_MANIFEST_DIR")).join("src"); + // The one file that may read the fields: `name_from` is above. + let exempt = Path::new("util.rs"); + + let mut files = Vec::new(); + rust_files(&src, &mut files); + files.sort(); + + let mut exempt_seen = false; + let mut reads = Vec::new(); + for file in &files { + let relative = file.strip_prefix(&src).expect("a path under src"); + if relative == exempt { + exempt_seen = true; + continue; + } + let text = std::fs::read_to_string(file).expect("read a source file"); + for (index, line) in text.lines().enumerate() { + if field_reads.iter().any(|field| line.contains(field)) { + reads.push(format!( + "{}:{}: {}", + relative.display(), + index + 1, + line.trim() + )); + } + } + } + + assert!( + exempt_seen, + "util.rs is not under {}; if it was renamed, rename it here too", + src.display() + ); + assert!( + reads.is_empty(), + "these lines read `local_name` or `advertisement_name`; use `peripheral_name`:\n{}", + reads.join("\n") + ); + } +} diff --git a/crates/aranet-core/tests/hardware_tests.rs b/crates/aranet-core/tests/hardware_tests.rs index 9cee3eb..754e77e 100644 --- a/crates/aranet-core/tests/hardware_tests.rs +++ b/crates/aranet-core/tests/hardware_tests.rs @@ -308,12 +308,20 @@ async fn test_concurrent_scans_are_serialised() { /// either search starts, and the test skips. /// /// When a scan ends, the scanning search's post-scan check and the waiting -/// search's re-check run at the same moment. Rarely, CoreBluetooth reports the -/// sensor just after the stop, and only one of the two checks sees it. If the -/// scanning search misses it, it finds the sensor in its next attempt's -/// re-check, both searches end with `CacheHit`, and the test passes. If the -/// waiting search misses it, it scans for itself and the test fails: rerun it -/// once. Without the re-check the test fails on every run. +/// search's re-check run at the same moment, and a sensor reported in the +/// scan's last moment can reach the adapter's list between the two, so that +/// only one of them sees it. This was rare on btleplug 0.11.8, where +/// CoreBluetooth could also report the sensor just after the stop. btleplug +/// 0.13.5 drops a report that its CoreBluetooth thread takes up after the stop +/// (`src/corebluetooth/internal.rs:1776-1784`; the reason is at `:723-728`). +/// That leaves less room for the rare case but does not remove it: `stop_scan` +/// returns as soon as the stop is queued for that thread +/// (`src/corebluetooth/adapter.rs:176-182`), and a second task adds each +/// reported sensor to the list (`adapter.rs:59-82`). If the scanning search +/// misses the sensor, it finds it in its next attempt's re-check, both searches +/// end with `CacheHit`, and the test passes. If the waiting search misses it, +/// it scans for itself and the test fails: rerun it once. Without the re-check +/// the test fails on every run. #[tokio::test] #[ignore = "requires BLE hardware: Aranet devices advertising nearby"] async fn test_concurrent_finds_share_one_scan() { @@ -1455,9 +1463,8 @@ fn test_get_adapter_still_discovers_after_its_runtime_shuts_down() { // ============================================================================= /// The adapter's peripheral for `device`: its scan identifier, its btleplug ID, or its -/// name (either half of CoreBluetooth's "GAP [advertised]" form), any case. `None` -/// when the adapter doesn't know it: CoreBluetooth forgets a peripheral once it -/// has disconnected, until a scan finds it again. +/// whole name, any case. `None` when the adapter doesn't know it: CoreBluetooth +/// forgets a peripheral once it has disconnected, until a scan finds it again. async fn known_peripheral(device: &str) -> Option { use btleplug::api::{Central as _, Peripheral as _}; @@ -1468,17 +1475,11 @@ async fn known_peripheral(device: &str) -> Option btleplug::platform::Peripheral { /// Whether the Bluetooth stack reports `device` as connected. `false` when the /// adapter doesn't know it (see `known_peripheral`) or doesn't answer within -/// 5 s: btleplug never answers for a peripheral that CoreBluetooth has dropped. +/// 5 s. The limit is a guard: btleplug 0.13.5 answers "not connected" at once +/// for a peripheral that its CoreBluetooth backend has forgotten +/// (`src/corebluetooth/internal.rs:1318-1332`), where 0.11.8 gave no answer. async fn peripheral_connected(device: &str) -> bool { let Some(p) = known_peripheral(device).await else { return false; diff --git a/crates/aranet-service/src/lib.rs b/crates/aranet-service/src/lib.rs index 832b990..edb3cbd 100644 --- a/crates/aranet-service/src/lib.rs +++ b/crates/aranet-service/src/lib.rs @@ -329,7 +329,23 @@ pub struct LoadedConfig { /// /// Each directive replaces a `RUST_LOG` directive for exactly its target: a /// known limit, so `RUST_LOG=aranet_store=debug`, for example, has no effect. -const DEFAULT_LOG_DIRECTIVES: &str = "aranet_service=info,tower_http=debug,aranet_store=warn"; +/// +/// The last directive turns off the log target of btleplug's CoreBluetooth +/// peripheral module. On macOS, btleplug 0.13.5 logs `Shouldn't get anything +/// but Ok!` at error level for every disconnect that CoreBluetooth confirms, +/// and then returns `Ok` (btleplug 0.13.5 +/// `src/corebluetooth/peripheral.rs:468-476`): the disconnect's own reply is +/// answered with "Device disconnected", like every other pending operation +/// (`src/corebluetooth/internal.rs:678-698`). The collector disconnects after +/// every poll, so the line would be logged once per poll per device. It is +/// that module's only warning or error. The cost is the limit above: no +/// `RUST_LOG` directive for that target, or for a shorter one such as +/// `btleplug=trace`, can show the module's lines (one error, one info and +/// four trace statements). btleplug has the module only on Apple platforms, +/// so the directive does nothing on Linux and Windows. Remove it when aranet +/// moves to a btleplug release that no longer logs the line. +const DEFAULT_LOG_DIRECTIVES: &str = "aranet_service=info,tower_http=debug,aranet_store=warn,\ + btleplug::corebluetooth::peripheral=off"; /// How long shutdown waits for background tasks after signalling them to /// stop, before aborting the ones left. @@ -1012,6 +1028,58 @@ mod tests { } } + /// On macOS, btleplug 0.13.5 logs `Shouldn't get anything but Ok!` at error + /// level for every disconnect that CoreBluetooth confirms, and the + /// collector disconnects after every poll. The default directives turn + /// that module's log target off: no `RUST_LOG` directive for that target, + /// or for a shorter one such as `btleplug=trace`, can show its lines. + /// btleplug's other modules and this crate's own lines are left alone. + #[test] + fn btleplugs_disconnect_error_stays_out_of_the_service_log() { + crate::test_support::register_silent_dispatcher(); + for rust_log in [ + "", + "warn", + "btleplug=trace", + "error,btleplug::corebluetooth::peripheral=trace", + ] { + let captured = Captured::default(); + let writer = captured.clone(); + let filter = with_default_directives(tracing_subscriber::EnvFilter::new(rust_log)) + .expect("the default directives parse"); + let subscriber = tracing_subscriber::fmt() + .with_env_filter(filter) + .with_ansi(false) + .with_writer(move || writer.clone()) + .finish(); + let _guard = tracing::subscriber::set_default(subscriber); + + tracing::error!( + target: "btleplug::corebluetooth::peripheral", + "Shouldn't get anything but Ok!" + ); + tracing::error!( + target: "btleplug::corebluetooth::internal", + "another btleplug error" + ); + tracing::info!("a service info line"); + + let logs = String::from_utf8(captured.0.lock().unwrap().clone()).unwrap(); + assert!( + logs.contains("ERROR btleplug::corebluetooth::internal: another btleplug error"), + "RUST_LOG={rust_log:?}: {logs}" + ); + assert!( + logs.contains("INFO aranet_service::tests: a service info line"), + "RUST_LOG={rust_log:?}: {logs}" + ); + assert!( + !logs.contains("btleplug::corebluetooth::peripheral"), + "RUST_LOG={rust_log:?}: {logs}" + ); + } + } + /// A config that monitors one device every 60 s. fn one_device_config() -> Config { Config { diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 35d3284..127aad2 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -4,7 +4,11 @@ Technical architecture and reference documentation for the Aranet Rust implement This project provides feature parity with [Aranet4-Python](https://github.com/Anrijs/Aranet4-Python) and beyond. > **Dependency Policy**: Always use the **latest stable versions** of all libraries, frameworks, and tools. -> Pin to major versions only (e.g., `btleplug = "0.11"` not `"0.11.4"`). Run `cargo update` regularly. +> Ask for the major version of a dependency, or for the minor version of a 0.x crate (`thiserror = "2"`, `tracing = "0.1"`). +> Ask for a later release only when the code needs something that release added or fixed, and say why in a comment +> above the requirement (`btleplug = "0.13.5"`). Requirements that name a later release without a comment +> (`tempfile = "3.10"`, `proptest = "1.9.0"`) are older than this rule; give each its reason when it is next changed. +> Run `cargo update` regularly. > Check [crates.io](https://crates.io) and [lib.rs](https://lib.rs) for current versions before adding dependencies. --- @@ -25,7 +29,7 @@ This project provides feature parity with [Aranet4-Python](https://github.com/An ### What's Working Now -- **aranet-core**: Complete BLE stack with btleplug 0.11 - scan, connect, device info, current readings, +- **aranet-core**: Complete BLE stack with btleplug 0.13 - scan, connect, device info, current readings, history download (V1+V2), settings read/write, auto-reconnection, streaming, notifications, RSSI, multi-device manager, event system, validation, thresholds, metrics, mock device - **aranet-types**: Shared types for CurrentReading, DeviceInfo, HistoryRecord, Status, DeviceType, all UUIDs @@ -236,7 +240,7 @@ path = "" # Empty = use default platform path | Dependency | Purpose | Min Version | Check Latest | |------------|---------|-------------|--------------| -| `btleplug` | Cross-platform BLE | 0.11+ | [crates.io/crates/btleplug](https://crates.io/crates/btleplug) | +| `btleplug` | Cross-platform BLE | 0.13.5+ | [crates.io/crates/btleplug](https://crates.io/crates/btleplug) | | `tokio` | Async runtime | 1.0+ | [crates.io/crates/tokio](https://crates.io/crates/tokio) | | `thiserror` | Error handling | 2.0+ | [crates.io/crates/thiserror](https://crates.io/crates/thiserror) | | `bytes` | Binary parsing | 1.0+ | [crates.io/crates/bytes](https://crates.io/crates/bytes) | @@ -902,8 +906,8 @@ Before building, learn from existing implementations: | Crate | Strengths | Weaknesses | btleplug Version | |-------|-----------|------------|------------------| -| `aranet` (m1guelpf) | Clean API, modern deps, device info | No history, no scanning | 0.11.4 (current) | -| `aranet-btle` (DDRBoxman) | BLE advertisement scanning | No device info, no history | 0.11 (current) | +| `aranet` (m1guelpf) | Clean API, modern deps, device info | No history, no scanning | 0.11.4 | +| `aranet-btle` (DDRBoxman) | BLE advertisement scanning | No device info, no history | 0.11 | | `aranet4` (lpraneis) | Historical data support | Uses OLD UUID only! | 0.9.1 (outdated) | | `aranet4-cli` (quentinms) | Multi-device, JSON output | CLI only, not a library | 0.9 (outdated) |