use std::sync::{Arc, PoisonError, RwLock};
use std::time::Duration;
use serde_json::{Value, json};
use crate::api::EeroApi;
use crate::auth::Session;
use crate::cache::{Cache, CacheKey};
use crate::consts;
use crate::envelope::Envelope;
use crate::error::Error;
use crate::storage::CredentialStore;
use crate::transport::{StorageFailures, Transport};
mod ac_compat;
mod account;
mod backup;
mod backup_access_points;
mod blacklist;
mod burst_reporters;
mod data_usage;
mod ddns;
mod devices;
mod dhcp;
mod diagnostics;
mod dns;
mod dns_policies;
mod eeros;
mod entitlements;
mod events;
mod forwards;
mod insights;
mod members;
mod networks;
mod notifications;
mod ouicheck;
mod permissions;
mod power_saving;
mod profiles;
mod reservations;
mod routing;
mod schedule;
mod security;
mod sqm;
mod subnets;
mod support;
mod thread;
mod transfer;
mod updates;
mod wan;
mod wpa3;
#[derive(Debug)]
pub struct Client {
api: EeroApi,
cache: Cache,
preferred_network_id: RwLock<Option<String>>,
}
impl Client {
#[must_use]
pub fn builder() -> ClientBuilder {
ClientBuilder::default()
}
#[must_use]
pub fn api(&self) -> &EeroApi {
&self.api
}
#[must_use]
pub fn is_authenticated(&self) -> bool {
self.api.is_authenticated()
}
#[must_use]
pub fn session(&self) -> Option<Session> {
self.api.auth().session()
}
pub fn clear_cache(&self) {
self.cache.clear();
}
pub fn set_preferred_network(&self, network_id: impl Into<String>) {
let mut guard = self
.preferred_network_id
.write()
.unwrap_or_else(PoisonError::into_inner);
*guard = Some(network_id.into());
}
#[must_use]
pub fn preferred_network_id(&self) -> Option<String> {
self.preferred_network_id
.read()
.unwrap_or_else(PoisonError::into_inner)
.clone()
}
async fn ensure_network_id(
&self,
network_id: Option<&str>,
auto_discover: bool,
) -> Result<String, Error> {
if let Some(id) = non_empty(network_id) {
return Ok(id.to_owned());
}
let preferred = self.preferred_network_id();
if let Some(id) = non_empty(preferred.as_deref()) {
return Ok(id.to_owned());
}
if auto_discover {
let response = self.get_networks(false).await?;
let networks = extract_networks_list(response.data());
if let Some(id) = networks.first().and_then(extract_network_id) {
return Ok(id);
}
}
Err(Error::MissingNetworkId)
}
pub async fn logout(&self) -> Result<bool, Error> {
let result = self.api.logout().await;
self.clear_cache();
result
}
pub fn set_session_token(&self, token: &str) -> Result<(), Error> {
self.api.auth().set_session_token(token)?;
self.clear_cache();
Ok(())
}
pub fn clear_session_token(&self) -> Result<(), Error> {
self.api.auth().clear_session_token()?;
self.clear_cache();
Ok(())
}
pub async fn get_account(&self, refresh_cache: bool) -> Result<Envelope, Error> {
if !refresh_cache && let Some(cached) = self.cache.get(&CacheKey::Account) {
return Ok(cached);
}
let response = self.api.networks().get_account().await?;
self.cache.put(CacheKey::Account, response.clone());
Ok(response)
}
pub async fn get_networks(&self, refresh_cache: bool) -> Result<Envelope, Error> {
if !refresh_cache && let Some(cached) = self.cache.get(&CacheKey::Networks) {
return Ok(cached);
}
let response = self.api.networks().get_networks().await?;
let networks = extract_networks_list(response.data());
let response = if networks.is_empty() {
self.apply_account_fallback(response).await?
} else {
response
};
self.cache.put(CacheKey::Networks, response.clone());
self.derive_preferred_network_id(&response);
Ok(response)
}
async fn apply_account_fallback(&self, original: Envelope) -> Result<Envelope, Error> {
let account_response = self.get_account(true).await?;
let account_networks = extract_account_networks(account_response.data());
if account_networks.is_empty() {
return Ok(original);
}
let meta = original
.as_value()
.get("meta")
.cloned()
.unwrap_or_else(|| json!({}));
Ok(Envelope::from_value(json!({
"meta": meta,
"data": {"networks": account_networks},
})))
}
fn derive_preferred_network_id(&self, response: &Envelope) {
if self.preferred_network_id().is_some() {
return;
}
let networks = extract_networks_list(response.data());
if let Some(id) = networks.first().and_then(extract_network_id) {
self.set_preferred_network(id);
}
}
#[allow(dead_code)] fn network_parent(&self, network_id: &str) -> Option<Value> {
self.cache
.get(&CacheKey::network(network_id))
.map(Envelope::into_value)
}
#[allow(dead_code)] fn find_by_id_or_url(envelopes: &[Value], resource_id: &str) -> Option<Value> {
envelopes
.iter()
.find(|entry| {
let Some(obj) = entry.as_object() else {
return false;
};
if obj.get("id").and_then(Value::as_str) == Some(resource_id) {
return true;
}
obj.get("url")
.and_then(Value::as_str)
.and_then(|url| crate::util::id_from_url(url).ok())
.is_some_and(|tail| tail == resource_id)
})
.cloned()
}
#[allow(dead_code)] fn eero_parent(&self, network_id: &str, eero_id: &str) -> Option<Value> {
let cached = self.cache.get(&CacheKey::eeros(network_id))?;
let data = cached.data().as_array()?;
Self::find_by_id_or_url(data, eero_id)
}
#[allow(dead_code)] fn device_parent(&self, network_id: &str, device_id: &str) -> Option<Value> {
self.cache
.get(&CacheKey::device(network_id, device_id))
.map(Envelope::into_value)
}
#[allow(dead_code)] fn invalidate_network_cache(&self, network_id: &str) {
self.cache.invalidate(&CacheKey::network(network_id));
}
#[allow(dead_code)] fn invalidate_eeros_cache(&self, network_id: &str) {
self.cache.invalidate(&CacheKey::eeros(network_id));
}
fn invalidate_device_cache(&self, network_id: &str, device_id: &str) {
self.cache
.invalidate(&CacheKey::device(network_id, device_id));
self.cache.invalidate(&CacheKey::devices(network_id));
}
fn invalidate_profile_cache(&self, network_id: &str, profile_id: &str) {
self.cache
.invalidate(&CacheKey::profile(network_id, profile_id));
self.cache.invalidate(&CacheKey::profiles(network_id));
}
fn invalidate_profiles_list_cache(&self, network_id: &str) {
self.cache.invalidate(&CacheKey::profiles(network_id));
}
}
fn extract_networks_list(data: &Value) -> Vec<Value> {
match data {
Value::Array(items) => items.clone(),
Value::Object(map) => truthy_array(map.get("networks"))
.or_else(|| truthy_array(map.get("data")))
.cloned()
.unwrap_or_default(),
_ => Vec::new(),
}
}
fn truthy_array(value: Option<&Value>) -> Option<&Vec<Value>> {
match value {
Some(Value::Array(items)) if !items.is_empty() => Some(items),
_ => None,
}
}
fn extract_network_id(entry: &Value) -> Option<String> {
if let Some(id) = entry
.get("id")
.and_then(Value::as_str)
.filter(|s| !s.is_empty())
.filter(|id| crate::routes::validate_segment(id).is_ok())
{
return Some(id.to_owned());
}
let url = entry
.get("url")
.and_then(Value::as_str)
.filter(|s| !s.is_empty())?;
let candidate = crate::util::id_from_url(url).ok()?;
crate::routes::validate_segment(&candidate).ok()?;
Some(candidate)
}
fn extract_account_networks(data: &Value) -> Vec<Value> {
let Some(account_data) = data.as_object() else {
return Vec::new();
};
match account_data.get("networks") {
Some(Value::Object(networks_data)) => networks_data
.get("data")
.and_then(Value::as_array)
.cloned()
.unwrap_or_default(),
Some(Value::Array(items)) => items.clone(),
_ => Vec::new(),
}
}
fn non_empty(value: Option<&str>) -> Option<&str> {
value.filter(|s| !s.is_empty())
}
#[derive(Debug)]
pub struct ClientBuilder {
http: Option<reqwest::ClientBuilder>,
base_url: Option<String>,
user_agent: Option<String>,
accept_language: Option<String>,
send_legacy_cookie: Option<bool>,
get_retries: Option<u32>,
session: Option<Session>,
store: Option<Arc<dyn CredentialStore>>,
storage_failures: StorageFailures,
cache_ttl: Duration,
}
impl Default for ClientBuilder {
fn default() -> Self {
Self {
http: None,
base_url: None,
user_agent: None,
accept_language: None,
send_legacy_cookie: None,
get_retries: None,
session: None,
store: None,
storage_failures: StorageFailures::default(),
cache_ttl: consts::DEFAULT_CACHE_TTL,
}
}
}
impl ClientBuilder {
#[must_use]
pub fn http_builder(mut self, builder: reqwest::ClientBuilder) -> Self {
self.http = Some(builder);
self
}
#[must_use]
pub fn base_url(mut self, base_url: impl Into<String>) -> Self {
self.base_url = Some(base_url.into());
self
}
#[must_use]
pub fn user_agent(mut self, user_agent: Option<String>) -> Self {
self.user_agent = user_agent;
self
}
#[must_use]
pub fn accept_language(mut self, accept_language: impl Into<String>) -> Self {
self.accept_language = Some(accept_language.into());
self
}
#[must_use]
pub fn send_legacy_cookie(mut self, send_legacy_cookie: bool) -> Self {
self.send_legacy_cookie = Some(send_legacy_cookie);
self
}
#[must_use]
pub fn get_retries(mut self, get_retries: u32) -> Self {
self.get_retries = Some(get_retries);
self
}
#[must_use]
pub fn session(mut self, session: Option<Session>) -> Self {
self.session = session;
self
}
#[must_use]
pub fn store(mut self, store: Option<Arc<dyn CredentialStore>>) -> Self {
self.store = store;
self
}
#[must_use]
pub fn storage_failures(mut self, storage_failures: StorageFailures) -> Self {
self.storage_failures = storage_failures;
self
}
#[must_use]
pub fn cache_ttl(mut self, cache_ttl: Duration) -> Self {
self.cache_ttl = cache_ttl;
self
}
pub async fn build(self) -> Result<Client, Error> {
let session = match self.session {
Some(session) => Some(session),
None => match &self.store {
Some(store) => match crate::storage::load_async(Arc::clone(store)).await {
Ok(loaded) => Some(loaded),
Err(err) => match self.storage_failures {
StorageFailures::Warn => {
tracing::warn!(
error = %err,
"failed to load initial session from credential store"
);
None
}
StorageFailures::Fatal => return Err(Error::Storage(err)),
},
},
None => None,
},
};
let mut transport_builder = Transport::builder()
.storage_failures(self.storage_failures)
.user_agent(self.user_agent)
.session(session)
.store(self.store);
if let Some(http) = self.http {
transport_builder = transport_builder.http_builder(http);
}
if let Some(base_url) = self.base_url {
transport_builder = transport_builder.base_url(base_url);
}
if let Some(accept_language) = self.accept_language {
transport_builder = transport_builder.accept_language(accept_language);
}
if let Some(send_legacy_cookie) = self.send_legacy_cookie {
transport_builder = transport_builder.send_legacy_cookie(send_legacy_cookie);
}
if let Some(get_retries) = self.get_retries {
transport_builder = transport_builder.get_retries(get_retries);
}
let transport = transport_builder.build()?;
let api = EeroApi::new(transport);
Ok(Client {
api,
cache: Cache::new(self.cache_ttl),
preferred_network_id: RwLock::new(None),
})
}
}
#[cfg(test)]
mod tests {
use super::{
Cache, CacheKey, Client, EeroApi, Envelope, extract_account_networks, extract_network_id,
extract_networks_list, non_empty,
};
use crate::transport::Transport;
use serde_json::json;
use std::sync::RwLock;
use std::time::Duration;
fn test_client() -> Client {
let transport = Transport::builder()
.build()
.expect("default transport configuration (no overrides) always builds successfully");
Client {
api: EeroApi::new(transport),
cache: Cache::new(Duration::from_secs(60)),
preferred_network_id: RwLock::new(None),
}
}
#[test]
fn extract_networks_list_from_a_bare_array() {
let data = json!([{"id": "1"}, {"id": "2"}]);
assert_eq!(
extract_networks_list(&data),
vec![json!({"id": "1"}), json!({"id": "2"})]
);
}
#[test]
fn extract_networks_list_prefers_the_networks_key() {
let data = json!({"networks": [{"id": "n1"}], "data": [{"id": "should-not-be-used"}]});
assert_eq!(extract_networks_list(&data), vec![json!({"id": "n1"})]);
}
#[test]
fn extract_networks_list_falls_back_to_the_data_key_when_networks_is_empty() {
let data = json!({"networks": [], "data": [{"id": "fallback"}]});
assert_eq!(
extract_networks_list(&data),
vec![json!({"id": "fallback"})]
);
}
#[test]
fn extract_networks_list_falls_back_to_the_data_key_when_networks_is_absent() {
let data = json!({"data": [{"id": "fallback"}]});
assert_eq!(
extract_networks_list(&data),
vec![json!({"id": "fallback"})]
);
}
#[test]
fn extract_networks_list_is_empty_when_neither_key_holds_a_non_empty_array() {
assert!(extract_networks_list(&json!({})).is_empty());
assert!(extract_networks_list(&json!({"networks": [], "data": []})).is_empty());
assert!(extract_networks_list(&json!(null)).is_empty());
assert!(extract_networks_list(&json!("not an object or array")).is_empty());
}
#[test]
fn extract_network_id_prefers_the_id_field() {
let entry = json!({"id": "abc123", "url": "/2.2/networks/999"});
assert_eq!(extract_network_id(&entry).as_deref(), Some("abc123"));
}
#[test]
fn extract_network_id_falls_back_to_the_url_tail_when_id_is_absent() {
let entry = json!({"url": "/2.2/networks/abc123"});
assert_eq!(extract_network_id(&entry).as_deref(), Some("abc123"));
}
#[test]
fn extract_network_id_falls_back_to_the_url_tail_when_id_is_empty() {
let entry = json!({"id": "", "url": "/2.2/networks/abc123/"});
assert_eq!(extract_network_id(&entry).as_deref(), Some("abc123"));
}
#[test]
fn extract_network_id_is_none_when_neither_field_is_usable() {
assert!(extract_network_id(&json!({})).is_none());
assert!(extract_network_id(&json!({"id": "", "url": ""})).is_none());
}
#[test]
fn extract_network_id_rejects_a_dot_segment_id_field_and_falls_back_to_url() {
let entry = json!({"id": "..", "url": "/2.2/networks/abc123"});
assert_eq!(extract_network_id(&entry).as_deref(), Some("abc123"));
}
#[test]
fn extract_network_id_rejects_a_dot_segment_id_field_with_no_usable_url() {
assert!(extract_network_id(&json!({"id": ".."})).is_none());
assert!(extract_network_id(&json!({"id": "."})).is_none());
}
#[test]
fn extract_network_id_rejects_a_url_tail_that_resolves_to_a_dot_segment() {
assert!(extract_network_id(&json!({"url": "/2.2/networks/.."})).is_none());
}
#[test]
fn extract_network_id_rejects_a_url_that_resolves_to_an_empty_segment() {
assert!(extract_network_id(&json!({"url": "/"})).is_none());
}
#[test]
fn extract_account_networks_from_a_nested_data_object() {
let data = json!({"networks": {"data": [{"id": "n1"}]}});
assert_eq!(extract_account_networks(&data), vec![json!({"id": "n1"})]);
}
#[test]
fn extract_account_networks_from_a_bare_array() {
let data = json!({"networks": [{"id": "n1"}]});
assert_eq!(extract_account_networks(&data), vec![json!({"id": "n1"})]);
}
#[test]
fn extract_account_networks_is_empty_for_any_other_shape() {
assert!(extract_account_networks(&json!({})).is_empty());
assert!(extract_account_networks(&json!({"networks": null})).is_empty());
assert!(extract_account_networks(&json!({"networks": {}})).is_empty());
assert!(extract_account_networks(&json!(null)).is_empty());
}
#[test]
fn non_empty_treats_an_empty_string_like_none() {
assert_eq!(non_empty(Some("")), None);
assert_eq!(non_empty(None), None);
assert_eq!(non_empty(Some("abc")), Some("abc"));
}
#[test]
fn network_parent_is_none_on_an_empty_cache() {
let client = test_client();
assert_eq!(client.network_parent("net1"), None);
}
#[test]
fn network_parent_returns_the_whole_cached_envelope_when_fresh() {
let client = test_client();
let envelope = json!({"meta": {"code": 200}, "data": {"name": "Home"}});
client.cache.put(
CacheKey::network("net1"),
Envelope::from_value(envelope.clone()),
);
assert_eq!(client.network_parent("net1"), Some(envelope));
}
#[test]
fn network_parent_is_none_once_the_entry_has_expired() {
let client = Client {
api: EeroApi::new(
Transport::builder()
.build()
.expect("default transport configuration always builds successfully"),
),
cache: Cache::new(Duration::ZERO), preferred_network_id: RwLock::new(None),
};
client.cache.put(
CacheKey::network("net1"),
Envelope::from_value(json!({"meta": {"code": 200}, "data": {"name": "Home"}})),
);
assert_eq!(client.network_parent("net1"), None);
}
#[test]
fn network_parent_is_scoped_to_its_own_network_id() {
let client = test_client();
client.cache.put(
CacheKey::network("net1"),
Envelope::from_value(json!({"meta": {"code": 200}, "data": {"name": "net1"}})),
);
assert_eq!(client.network_parent("net2"), None);
}
#[test]
fn find_by_id_or_url_matches_the_bare_id_field() {
let envelopes = [json!({"id": "e1", "url": "/2.2/eeros/other"})];
assert_eq!(
Client::find_by_id_or_url(&envelopes, "e1"),
Some(envelopes[0].clone())
);
}
#[test]
fn find_by_id_or_url_falls_back_to_the_url_trailing_segment() {
let envelopes = [json!({"url": "/2.2/eeros/e1"})];
assert_eq!(
Client::find_by_id_or_url(&envelopes, "e1"),
Some(envelopes[0].clone())
);
}
#[test]
fn find_by_id_or_url_returns_none_when_nothing_matches() {
let envelopes = [
json!({"id": "e1", "url": "/2.2/eeros/e1"}),
json!({"id": "e2", "url": "/2.2/eeros/e2"}),
];
assert_eq!(Client::find_by_id_or_url(&envelopes, "e3"), None);
}
#[test]
fn find_by_id_or_url_skips_non_object_entries() {
let envelopes = [json!("not an object"), json!({"id": "e1"})];
assert_eq!(
Client::find_by_id_or_url(&envelopes, "e1"),
Some(json!({"id": "e1"}))
);
}
#[test]
fn find_by_id_or_url_ignores_a_url_that_id_from_url_itself_rejects() {
let envelopes = [json!({"url": "/"})];
assert_eq!(Client::find_by_id_or_url(&envelopes, ""), None);
}
#[test]
fn eero_parent_is_none_on_an_empty_cache() {
let client = test_client();
assert_eq!(client.eero_parent("net1", "eero1"), None);
}
#[test]
fn eero_parent_finds_the_matching_entry_in_the_cached_eeros_list() {
let client = test_client();
let eero_entry = json!({"id": "eero1", "url": "/2.2/eeros/eero1"});
client.cache.put(
CacheKey::eeros("net1"),
Envelope::from_value(json!({
"meta": {"code": 200},
"data": [eero_entry.clone(), {"id": "eero2"}],
})),
);
assert_eq!(client.eero_parent("net1", "eero1"), Some(eero_entry));
}
#[test]
fn eero_parent_is_none_when_the_id_is_not_in_the_cached_list() {
let client = test_client();
client.cache.put(
CacheKey::eeros("net1"),
Envelope::from_value(json!({"meta": {"code": 200}, "data": [{"id": "eero2"}]})),
);
assert_eq!(client.eero_parent("net1", "eero1"), None);
}
#[test]
fn eero_parent_is_none_when_the_cached_datas_shape_is_not_an_array() {
let client = test_client();
client.cache.put(
CacheKey::eeros("net1"),
Envelope::from_value(json!({"meta": {"code": 200}, "data": {}})),
);
assert_eq!(client.eero_parent("net1", "eero1"), None);
}
#[test]
fn eero_parent_is_none_once_the_entry_has_expired() {
let client = Client {
api: EeroApi::new(
Transport::builder()
.build()
.expect("default transport configuration always builds successfully"),
),
cache: Cache::new(Duration::ZERO),
preferred_network_id: RwLock::new(None),
};
client.cache.put(
CacheKey::eeros("net1"),
Envelope::from_value(json!({"meta": {"code": 200}, "data": [{"id": "eero1"}]})),
);
assert_eq!(client.eero_parent("net1", "eero1"), None);
}
#[test]
fn device_parent_is_none_on_an_empty_cache() {
let client = test_client();
assert_eq!(client.device_parent("net1", "dev1"), None);
}
#[test]
fn device_parent_returns_the_whole_cached_envelope_when_fresh() {
let client = test_client();
let envelope = json!({"meta": {"code": 200}, "data": {"mac": "dev1"}});
client.cache.put(
CacheKey::device("net1", "dev1"),
Envelope::from_value(envelope.clone()),
);
assert_eq!(client.device_parent("net1", "dev1"), Some(envelope));
}
#[test]
fn device_parent_is_scoped_to_its_own_device_id() {
let client = test_client();
client.cache.put(
CacheKey::device("net1", "dev1"),
Envelope::from_value(json!({"meta": {"code": 200}, "data": {"mac": "dev1"}})),
);
assert_eq!(client.device_parent("net1", "dev2"), None);
}
#[test]
fn device_parent_is_none_once_the_entry_has_expired() {
let client = Client {
api: EeroApi::new(
Transport::builder()
.build()
.expect("default transport configuration always builds successfully"),
),
cache: Cache::new(Duration::ZERO),
preferred_network_id: RwLock::new(None),
};
client.cache.put(
CacheKey::device("net1", "dev1"),
Envelope::from_value(json!({"meta": {"code": 200}, "data": {"mac": "dev1"}})),
);
assert_eq!(client.device_parent("net1", "dev1"), None);
}
#[test]
fn invalidate_network_cache_drops_only_the_network_entry() {
let client = test_client();
client.cache.put(
CacheKey::network("net1"),
Envelope::from_value(json!({"meta": {"code": 200}, "data": {}})),
);
client.invalidate_network_cache("net1");
assert_eq!(client.cache.get(&CacheKey::network("net1")), None);
}
#[test]
fn invalidate_eeros_cache_drops_only_the_eeros_list_entry() {
let client = test_client();
client.cache.put(
CacheKey::eeros("net1"),
Envelope::from_value(json!({"meta": {"code": 200}, "data": []})),
);
client.invalidate_eeros_cache("net1");
assert_eq!(client.cache.get(&CacheKey::eeros("net1")), None);
}
}