rusteero 3.0.1

Async Rust client for the Eero (Amazon) mesh Wi-Fi cloud API — a port of the Python eero-api library
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
//! Shared wiremock test harness (`MockEero`) used by every HTTP integration test.
//!
//! This file is a *module*, not its own integration-test binary: it lives at
//! `tests/common/mod.rs` rather than `tests/common.rs` specifically so cargo never tries to run
//! it as a standalone test target.
//! Any file directly under `tests/` pulls it in with `mod common;`.
//!
//! [`MockEero`] answers one design question up front, correctly, for every test written against
//! it: [`Transport::builder`]'s `base_url` setter derives *both*
//! the `/2.2` and `/2.3` bases from the same root (see `src/transport.rs`'s
//! `TransportBuilder::base_url` docs), so a single `wiremock::MockServer` stands in for the real
//! Eero cloud's two hosts — a test can assert a device PUT really went to `/2.3/...` while a GET
//! from the same [`Transport`] went to `/2.2/...`, exactly like the real API.

// Not every helper here has a caller in every test binary that pulls in this module with `mod
// common;` — e.g. `transport_with_store` has no caller in `harness_smoke.rs`, but is required
// surface for the client+cache suite and the storage-backed auth tests. A plain `cargo clippy`
// would otherwise flag whichever subset any one binary doesn't happen to call as dead code.
#![allow(dead_code)]

use std::path::PathBuf;
use std::sync::{Arc, Mutex, PoisonError};

use tracing::field::{Field, Visit};
use tracing::subscriber::DefaultGuard;
use tracing::{Event, Level, Subscriber};
use tracing_subscriber::layer::{Context, SubscriberExt};
use tracing_subscriber::{Layer, registry};
use wiremock::MockServer;
use wiremock::matchers::{HeaderExactMatcher, header};

use rusteero::auth::AuthApi;
use rusteero::auth::Session;
use rusteero::auth::flow::LoginFlow;
use rusteero::storage::CredentialStore;
use rusteero::transport::Transport;

/// A session token every wiremock test can share, so no individual test hand-writes the literal
/// `"s=test-token"` cookie value.
///
/// Pair with [`session_cookie`] to match a request authenticated with this token, or
/// [`session_cookie_for`] for any other token (e.g. one obtained from a fixture).
pub const TEST_TOKEN: &str = "test-token";

/// A running wiremock server plus the handful of `rusteero` entry points every HTTP integration
/// test needs, all pre-wired to point at it.
///
/// Build one with [`MockEero::start`], register `wiremock::Mock`s against `mock.server`, then
/// build whichever `rusteero` type the test under way needs
/// ([`MockEero::transport_with_token`], [`MockEero::login_flow`],
/// [`MockEero::auth_api_with_token`], ...) — every one of them already points at
/// [`MockEero::uri`] for *both* API versions (see the module docs).
pub struct MockEero {
    /// The running mock server. Public so a test can `Mock::given(..).mount(&mock.server)`
    /// directly and rely on `wiremock`'s own `.expect(n)` call-count verification, which runs
    /// when the returned guard is dropped.
    pub server: MockServer,
}

impl MockEero {
    /// Starts a fresh wiremock server bound to an ephemeral local port.
    pub async fn start() -> Self {
        Self {
            server: MockServer::start().await,
        }
    }

    /// The mock server's base URL (e.g. `http://127.0.0.1:54321`), with no trailing slash.
    #[must_use]
    pub fn uri(&self) -> String {
        self.server.uri()
    }

    /// Builds a [`Transport`] pointed at this mock server with no session and no credential
    /// store configured — for exercising the unauthenticated paths (`LoginFlow::start`, the
    /// "Not authenticated" precondition, a fresh `refresh_session` with nothing to refresh, ...).
    #[must_use]
    pub fn transport_anonymous(&self) -> Transport {
        Transport::builder()
            .base_url(self.uri())
            .build()
            .expect("a `MockServer`'s own URI is always a valid base URL")
    }

    /// Builds a [`Transport`] pointed at this mock server, pre-seeded with a valid session
    /// carrying `token` (via [`Session::from_token`]) and no credential store.
    #[must_use]
    pub fn transport_with_token(&self, token: &str) -> Transport {
        Transport::builder()
            .base_url(self.uri())
            .session(Some(Session::from_token(token)))
            .build()
            .expect("a `MockServer`'s own URI is always a valid base URL")
    }

    /// Builds a [`Transport`] pointed at this mock server, pre-seeded with a valid session
    /// carrying `token`, backed by `store` — for exercising persistence side effects
    /// (`Transport::set_session`, `Transport::refresh_session`, the three
    /// `AuthApi::clear_*`/`logout` scopes, ...).
    #[must_use]
    pub fn transport_with_store(&self, token: &str, store: Arc<dyn CredentialStore>) -> Transport {
        Transport::builder()
            .base_url(self.uri())
            .session(Some(Session::from_token(token)))
            .store(Some(store))
            .build()
            .expect("a `MockServer`'s own URI is always a valid base URL")
    }

    /// Builds a [`LoginFlow`] pointed at this mock server, with no session and no credential
    /// store — the seam the interactive login handshake tests use.
    #[must_use]
    pub fn login_flow(&self) -> LoginFlow {
        LoginFlow::with_transport(self.transport_anonymous())
    }

    /// Builds an [`AuthApi`] pointed at this mock server, wrapping a [`Transport`] already
    /// authenticated with `token` (see [`MockEero::transport_with_token`]).
    #[must_use]
    pub fn auth_api_with_token(&self, token: &str) -> AuthApi {
        AuthApi::new(self.transport_with_token(token))
    }
}

/// Matches a request's `Cookie` header against exactly `s=`[`TEST_TOKEN`].
///
/// The shared matcher every test built on
/// `mock.`[`transport_with_token`](MockEero::transport_with_token)`(TEST_TOKEN)` should use, so
/// the literal cookie string is written in exactly one place in the whole test suite.
#[must_use]
pub fn session_cookie() -> HeaderExactMatcher {
    session_cookie_for(TEST_TOKEN)
}

/// Matches a request's `Cookie` header against exactly `s=<token>`, for tests that authenticate
/// with a token other than [`TEST_TOKEN`] (e.g. a freshly-verified login token, or a
/// post-refresh token read out of a fixture).
#[must_use]
pub fn session_cookie_for(token: &str) -> HeaderExactMatcher {
    header("cookie", format!("s={token}"))
}

/// Matches a request's `X-User-Token` header against exactly [`TEST_TOKEN`] — the *primary*
/// credential at `v8.0.4` (see `src/transport.rs`'s credential-placement docs). Pair with
/// [`session_cookie`] to assert both the primary header and the legacy cookie are present.
#[must_use]
pub fn user_token_header() -> HeaderExactMatcher {
    user_token_header_for(TEST_TOKEN)
}

/// Matches a request's `X-User-Token` header against exactly `token`. See [`session_cookie_for`]
/// for the sibling legacy-cookie matcher.
#[must_use]
pub fn user_token_header_for(token: &str) -> HeaderExactMatcher {
    header("x-user-token", token)
}

/// Reads a fixture file's contents as a `String`.
///
/// `name` is a bare file name (e.g. `"devices.json"`), resolved against this crate's
/// `tests/fixtures/` directory regardless of the current working directory `cargo test` happens
/// to run from.
///
/// # Panics
///
/// Panics if `name` does not exist under `tests/fixtures/` or cannot be read — a missing fixture
/// is a test-authoring bug, not a runtime condition any test should handle gracefully.
#[must_use]
pub fn fixture(name: &str) -> String {
    let path = fixture_path(name);
    std::fs::read_to_string(&path)
        .unwrap_or_else(|err| panic!("failed to read fixture {}: {err}", path.display()))
}

/// Reads and parses a fixture file as a [`serde_json::Value`]. See [`fixture`] for the panic
/// contract this shares.
///
/// # Panics
///
/// Panics under the same conditions as [`fixture`], and additionally if the file's contents are
/// not valid JSON.
#[must_use]
pub fn fixture_json(name: &str) -> serde_json::Value {
    serde_json::from_str(&fixture(name))
        .unwrap_or_else(|err| panic!("fixture {name} is not valid JSON: {err}"))
}

/// Resolves `name` against this crate's `tests/fixtures/` directory.
fn fixture_path(name: &str) -> PathBuf {
    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
        .join("tests")
        .join("fixtures")
        .join(name)
}

// ===================== log capture =====================

/// One captured `tracing` event: its [`Level`], its target (the emitting module path, e.g.
/// `rusteero::links`), and its `message` field rendered as text.
///
/// Structured fields other than `message` (`error = %err`, `attempt`, `path`, ...) are kept
/// alongside, in event order; read them with [`LogCapture::fields`] / [`LogCapture::field`].
pub type LogRecord = (Level, String, String);

/// The structured fields of one captured event other than `message`, as `(name, rendered value)`
/// pairs in the order the event recorded them. String values arrive verbatim (no quotes),
/// `Display`-captured values (`%x`) as their `Display` text and `Debug`-captured ones (`?x`) as
/// their `Debug` text.
pub type LogFields = Vec<(String, String)>;

/// Keeps a [`capture_logs`] subscriber installed on the current thread; dropping it restores the
/// subscriber that was in place before. Bind it to a named variable (`let (_guard, logs) = ...`,
/// not `_`), or the capture ends immediately.
pub type LogGuard = DefaultGuard;

/// A handle onto the events [`capture_logs`] recorded on the current thread. Cheap to clone; every
/// clone sees the same records, and the handle stays readable after its [`LogGuard`] is dropped.
#[derive(Clone, Default)]
pub struct LogCapture {
    records: Arc<Mutex<Vec<(LogRecord, LogFields)>>>,
}

impl LogCapture {
    /// Every captured event, oldest first.
    #[must_use]
    pub fn records(&self) -> Vec<LogRecord> {
        self.lock()
            .iter()
            .map(|(record, _)| record.clone())
            .collect()
    }

    /// Every captured event together with its structured fields, oldest first. For hygiene checks
    /// that must see what a formatting subscriber would print on the same line: the fields are
    /// not part of [`LogCapture::records`].
    #[must_use]
    pub fn entries(&self) -> Vec<(LogRecord, LogFields)> {
        self.lock().clone()
    }

    /// The messages of every captured event at exactly `level`, oldest first.
    #[must_use]
    pub fn messages(&self, level: Level) -> Vec<String> {
        self.lock()
            .iter()
            .filter(|((record_level, ..), _)| *record_level == level)
            .map(|((.., message), _)| message.clone())
            .collect()
    }

    /// The messages of every captured `WARN` event, oldest first.
    #[must_use]
    pub fn warnings(&self) -> Vec<String> {
        self.messages(Level::WARN)
    }

    /// The messages of every captured `ERROR` event, oldest first.
    #[must_use]
    pub fn errors(&self) -> Vec<String> {
        self.messages(Level::ERROR)
    }

    /// Whether any captured event at exactly `level` has a message containing `needle`.
    #[must_use]
    pub fn contains(&self, level: Level, needle: &str) -> bool {
        self.lock().iter().any(|((record_level, _, message), _)| {
            *record_level == level && message.contains(needle)
        })
    }

    /// How many captured events at exactly `level` have a message containing `needle`.
    #[must_use]
    pub fn count(&self, level: Level, needle: &str) -> usize {
        self.lock()
            .iter()
            .filter(|((record_level, _, message), _)| {
                *record_level == level && message.contains(needle)
            })
            .count()
    }

    /// The structured fields of the first captured event at exactly `level` whose message
    /// contains `needle`, or `None` if no such event was captured.
    #[must_use]
    pub fn fields(&self, level: Level, needle: &str) -> Option<LogFields> {
        self.lock()
            .iter()
            .find(|((record_level, _, message), _)| {
                *record_level == level && message.contains(needle)
            })
            .map(|(_, fields)| fields.clone())
    }

    /// The rendered value of field `name` on the first captured event at exactly `level` whose
    /// message contains `needle`, or `None` if there is no such event or field.
    #[must_use]
    pub fn field(&self, level: Level, needle: &str, name: &str) -> Option<String> {
        self.fields(level, needle)?
            .into_iter()
            .find(|(field_name, _)| field_name == name)
            .map(|(_, value)| value)
    }

    /// Whether any captured event, at any level, has `needle` in its message or in the rendered
    /// value of one of its structured fields. For leak assertions: a credential that reaches the
    /// log through `error = %err` or `token = %x` is as much a leak as one in the message.
    #[must_use]
    pub fn mentions(&self, needle: &str) -> bool {
        self.lock().iter().any(|((_, _, message), fields)| {
            message.contains(needle) || fields.iter().any(|(_, value)| value.contains(needle))
        })
    }

    /// Whether nothing at all has been captured.
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.lock().is_empty()
    }

    /// Forgets everything captured so far, e.g. to drop the noise of a test's setup phase before
    /// the call under test.
    pub fn clear(&self) {
        self.lock().clear();
    }

    fn lock(&self) -> std::sync::MutexGuard<'_, Vec<(LogRecord, LogFields)>> {
        // A panic while a test thread held the lock must not hide the records from the
        // assertion that reports it.
        self.records.lock().unwrap_or_else(PoisonError::into_inner)
    }
}

/// Collects the `message` field of one event, plus every other field as rendered text.
#[derive(Default)]
struct MessageVisitor {
    message: String,
    fields: LogFields,
}

impl Visit for MessageVisitor {
    fn record_str(&mut self, field: &Field, value: &str) {
        if field.name() == "message" {
            value.clone_into(&mut self.message);
        } else {
            self.fields
                .push((field.name().to_owned(), value.to_owned()));
        }
    }

    fn record_debug(&mut self, field: &Field, value: &dyn std::fmt::Debug) {
        if field.name() == "message" {
            self.message = format!("{value:?}");
        } else {
            self.fields
                .push((field.name().to_owned(), format!("{value:?}")));
        }
    }
}

/// The `tracing` layer behind [`capture_logs`]: appends every event, at every level, to a shared
/// vector.
struct CaptureLayer {
    records: Arc<Mutex<Vec<(LogRecord, LogFields)>>>,
}

impl<S: Subscriber> Layer<S> for CaptureLayer {
    fn on_event(&self, event: &Event<'_>, _ctx: Context<'_, S>) {
        let mut visitor = MessageVisitor::default();
        event.record(&mut visitor);
        let metadata = event.metadata();
        self.records
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .push((
                (
                    *metadata.level(),
                    metadata.target().to_owned(),
                    visitor.message,
                ),
                visitor.fields,
            ));
    }
}

/// Installs a capturing `tracing` subscriber for the **current thread** and returns the
/// [`LogGuard`] that keeps it installed plus the [`LogCapture`] handle to read what was logged.
///
/// Use it to pin a changed or new `WARN`/`ERROR` line, or to prove a warning was *not* emitted:
///
/// ```ignore
/// let (_guard, logs) = common::capture_logs();
/// // ... drive the call under test ...
/// assert!(logs.contains(tracing::Level::WARN, "Issuing write (set nightlight for eero)"));
/// ```
///
/// Events are captured at every level and from every crate, so filter by level and message text
/// rather than counting all records.
///
/// # Current thread only
///
/// The subscriber is installed with `tracing::subscriber::set_default`, which is thread-local.
/// That is exactly right for `#[tokio::test]`, whose default runtime is current-thread, so every
/// task the test spawns runs on the test's own thread. Events logged on any other thread — a
/// `#[tokio::test(flavor = "multi_thread")]` worker, a `std::thread::spawn`ed thread, reqwest's
/// connection tasks on a separate runtime — are **not** captured, unless the code that hops threads
/// carries the caller's dispatcher across (the crate's `storage::*_async` adapters do, so a
/// credential store's own lines are captured). The capture is also isolated per test: tests running in parallel on their own
/// threads never see each other's events.
///
/// # Parallel tests
///
/// `tracing-core` keeps one process-wide interest cache per callsite. While only one dispatcher
/// exists it decides a newly hit callsite against the *calling* thread's default alone, so a
/// parallel test thread with no subscriber can cache "never" for a library callsite before this
/// capture is installed, and the capture then misses that event. An always-live anchor
/// dispatcher, registered once per test binary, keeps every interest decision consulting all
/// live dispatchers, this capture included.
#[must_use]
pub fn capture_logs() -> (LogGuard, LogCapture) {
    static ANCHOR: std::sync::OnceLock<tracing::Dispatch> = std::sync::OnceLock::new();
    ANCHOR.get_or_init(|| tracing::Dispatch::new(registry()));
    let capture = LogCapture::default();
    let subscriber = registry().with(CaptureLayer {
        records: Arc::clone(&capture.records),
    });
    (tracing::subscriber::set_default(subscriber), capture)
}