Repository navigation
Migration
Upgrade guide between rusteero major releases. The crate tracks the Python
eero-api library, so each rusteero major maps
onto an eero-api release: 1.0.0 ported eero-api 6.2.0, 2.0.0 ported 8.0.4, and 3.0.0 ports
8.4.1. Where a change below has a Python counterpart, the Python
Migration page (v6.x → v7.0.0 and
v7.x → v8.0.0) and its Deprecations
register give the wire-level reasoning.
What broke: four signature changes, listed first; the compiler finds every one of them (with one caveat for the async setters, see 3). Everything else in this release is either new surface or a change of behaviour behind an unchanged signature, which the compiler cannot point you to, so read Behaviour changes as well.
Both variants gained status: Option<u16>. A server-driven Authentication carries
Some(401), including a 401 whose meta.error is error.rate.limit. A RateLimit carries the
response's own status: Some(429), or for example Some(400) or Some(503) when
error.rate.limit arrives on another status. The local "Not authenticated" guard and the
"Login failed: …" / "Verification failed: …" errors that LoginFlow::start and
PendingLogin::verify build around another failure carry None; a real 401 from login or verify
keeps Some(401). A struct literal or a pattern that lists every field no longer compiles: add
status, or end the pattern with ...
// Before (2.x)
match err {
Error::Authentication { message, envelope, error_code } => { /* … */ }
Error::RateLimit { message, retry_after, envelope, error_code } => { /* … */ }
_ => {}
}
let local = Error::Authentication { message: "no token".into(), envelope: None, error_code: None };
// After (3.0.0)
match err {
Error::Authentication { error_code, status, .. } => { /* status: Some(401), or None if local */ }
Error::RateLimit { retry_after, status, .. } => { /* status: Some(429), Some(503), … */ }
_ => {}
}
let local = Error::authentication("no token"); // status: NoneError::status() returns the new field, so it is now Some(401) / Some(429) (or whatever the
response carried) for these two variants, where 2.x returned None. is_auth_error() is
unchanged in effect: true for every Authentication, false for every RateLimit whatever its
status.
The nine time-windowed data-usage reads gained a timeout parameter, immediately before
network_id on Client and immediately before parent on DataUsageApi:
Client |
client.api().data_usage() |
|---|---|
get_data_usage |
get_data_usage |
get_data_usage_breakdown |
get_breakdown |
get_devices_data_usage |
get_devices_usage |
get_device_data_usage |
get_device_usage |
get_eeros_data_usage_summary |
get_eeros_summary |
get_eero_data_usage |
get_eero_usage |
get_profile_data_usage |
get_profile_usage |
get_unprofiled_devices_data_usage |
get_unprofiled_devices |
get_unprofiled_data_usage_summary |
get_unprofiled_summary |
// Before (2.x)
client.get_data_usage(start, end, "daily", None, None).await?;
client.get_device_data_usage(mac, start, end, "hourly", None, None).await?;
api.data_usage().get_data_usage(&nid, start, end, "daily", None, None).await?;
// After (3.0.0): None keeps the transport default (30 s total, 10 s per read)
client.get_data_usage(start, end, "daily", None, None, None).await?;
client.get_device_data_usage(mac, start, end, "hourly", None, None, None).await?;
api.data_usage().get_data_usage(&nid, start, end, "daily", None, None, None).await?;
// Or give a long hourly window more time
use rusteero::RequestTimeout;
use std::time::Duration;
let slow = RequestTimeout::new(Some(Duration::from_secs(120)), Some(Duration::from_secs(30)));
client.get_data_usage(start, end, "hourly", None, Some(slow), None).await?;Some(t) replaces both bounds for that one request: a field left None, or set to
Duration::ZERO, is unbounded and never falls back to the default, so
RequestTimeout::total(d) has no read bound at all. The new get_eeros_data_usage /
get_eeros_usage takes timeout in the same place. get_data_usage_report_settings and
set_data_usage_report_settings are unchanged. See
Configuration — Transport options for the full semantics.
AuthApi::{set_session_token, clear_session_token, clear_auth_data} and
Client::{set_session_token, clear_session_token} are now async fn:
// Before (2.x)
client.set_session_token("<token>")?;
client.clear_session_token()?;
client.api().auth().clear_auth_data()?;
// After (3.0.0)
client.set_session_token("<token>").await?;
client.clear_session_token().await?;
client.api().auth().clear_auth_data().await?;
client.clear_auth_data().await?; // new on Client; also drops an explicit preferred networkThe caveat: client.set_session_token("<token>")? stops compiling, but a bare statement such as
client.clear_session_token(); (no ?, no .await) still compiles, with only an
unused_must_use warning, and does nothing. Build with -D warnings, or grep for the five
names.
Each call replaces the in-memory session before its first .await yields, so every other task
sees the change at once, then runs the credential-store write on Tokio's blocking pool, where
dropping the future no longer cancels it. When several changes overlap, the last one applied wins
in memory and in the store. They need a Tokio runtime (current-thread or multi-thread); from
synchronous code, drive them with your runtime's block_on. Transport::set_session stays
synchronous and blocks on the store; Transport::set_session_async is its async counterpart.
// Before (2.x)
client.api().burst_reporters().create_burst_reporter(&nid, json!({}), None).await?;
// After (3.0.0)
client.api().burst_reporters().create_burst_reporter(&nid, None, None).await?; // sends ""
client.create_burst_reporter(None, None).await?; // new Client wrapperNone (or Some(Value::Null)) sends the two-byte JSON string "", the body that was verified
against a live network, and logs nothing. Any other Some(..) first logs a deprecation WARN.
A falsy value (false, 0, "", [], {}) is then ignored and "" is sent; a truthy one is
still sent as the JSON body, with an uncharacterised-write warning. The parameter goes away when
eero-api 9.0.0 removes it. Rust cannot mark a single parameter #[deprecated], so the compiler
does not flag a Some(..): grep for it.
These keep their signatures, so they compile unchanged and behave differently.
Requests and responses
-
New default
User-Agent:eero-ios/2026.8.1 (iPhone; iOS 18.5)(consts::DEFAULT_USER_AGENT), replacingeero/3.0 (iPhone; iOS 17.0), for every request, login and refresh included. The API reads it as the app version and advertises more capabilities to the new string (led_action,device_blacklist,diagnostics,device_usage,block_apps,ddns_enabled,historical_usage, thednsfilter_*entries and more were missing under the old one). Under it, the network'sresourcesmap also pointsforwards,routingandsupportat API 2.3; the three reads are pinned to 2.2 (below), so their shape does not change. To keep the previous string:use rusteero::consts::LEGACY_USER_AGENT; let client = Client::builder() .session(Some(session)) .user_agent(Some(LEGACY_USER_AGENT.to_owned())) .build() .await?;
LoginFlow::new(..)sends the default;LoginFlow::with_transport(transport)sends whatever that transport was built with. See Configuration — TheUser-Agent. -
Version pins.
get_support,get_forwardsandget_routing(domain andClient) always go to API 2.2, even when aparentenvelope publishes a 2.3 link: on 2.3,supportreturns acontactsarray instead of a flat object.set_device_nicknameandpause_devicealways go to 2.3, and so do the WAN methods (get_multistaticip,set_multistaticip,set_secondary_wan_config,set_device_secondary_wan_access), whatever form the network takes: a/2.2/networks/<id>path or a 2.2 URL no longer carries its version into the request.get_multistaticipis re-pinned even when it follows a published link. -
A
2xxbody that is valid JSON but not an object (a list, a string, a number,true,null) is nowError::ApiwithUnexpected JSON response: expected an object, where 2.x returned it wrapped in anEnvelope. A2xxbody that is not UTF-8 isError::ApiwithResponse body is not valid UTF-8. A non-2xxbody is decoded lossily, so a stray invalid byte no longer hides its status. -
Retry-Afteris capped at 24 hours (consts::RETRY_AFTER_MAX) before it reachesError::RateLimit'sretry_after. Delta-seconds must be plain ASCII digits (a leading+is no longer accepted), and an HTTP date may now also be in RFC 850 or asctime form, not only an IMF-fixdate. -
get_retriesfollows the classified error: it retriesError::Network,Error::Timeoutand any error whose status is500or more, except a rate limit on any status (a5xxcarryingerror.rate.limitis no longer retried). -
TransportBuilder::timeout(Duration::ZERO)andread_timeout(Duration::ZERO)now switch that bound off (unbounded), where 2.x timed out at once. The crate now enforces both bounds itself: the read bound also covers connecting, writing the request and waiting for the response head. -
set_thread_enabledis now an alias ofupdate_thread(Some(enabled), None, ..): it sends{"thread_enable": enabled}instead of{"enabled": enabled}, still as a JSONPUTtonetworks/{id}/thread, and logsupdate_thread's warning. It remains unverified. -
set_dhcp(Some("manual"), ..)is sent as"custom", the value the API accepts (it refuses a literal"manual"with400);"custom"is now accepted as a mode too. Every DHCP write is confirmed to restart the whole mesh, about eight minutes of outage. -
add_to_blacklist,block_deviceandcreate_burst_reporter(with the""body) were verified against a live network and no longer log the uncharacterised-write warning.
Validation, before anything is sent
-
Empty names and passwords are rejected.
set_network_name,set_network_password,set_guest_passwordandset_guest_network(.., Some(""), ..)given""returnError::Validation { field: "name" | "password", message: "must be a non-empty string" }, onClientbefore the network is resolved or discovered. 2.x sent the request. -
Changed
Validationfield names. Match on these if you inspectfield:Check 2.x field3.0.0 fieldA path you pass as a resource argument ( /2.2/networks/<id>)"link""id_or_url"(a link read from aparentenvelope keeps"link")The User-Agentbuilder value"user_agent""User-Agent", checked after"X-Accept-Language"base_url"base_url", messagenot a valid URL: <parser text>"base_url", with one of the fixed messagesmust be an absolute URL with a scheme and a host,must not carry userinfoorhas an authority that cannot be parsed;""is rejectedAn absolute URL off the API origin "url",must be an absolute <scheme> URL on <host>"url",must be an absolute <scheme> URL on <host> with no userinfo and no other portA request URL with userinfo passed to Transport::requestsent "url",must not carry userinfo(reqwest would send it as Basic credentials)ClientBuilder::build()now checksbase_url,X-Accept-LanguageandUser-Agent, in that order, before it reads a credential store. See Troubleshooting for every field. -
Stricter paths and URLs. A path or absolute URL you pass must now name exactly one resource of the family the method addresses (
/<version>/networks/<id>where a network is expected), so/2.2/accountpassed as a network, or a network path passed toreboot_eero, ismust be a path under <family> on the API host. It must also be a plain path: no whitespace or control character, no query or fragment, no./..segment or percent-encoded dot, no backslash. An absolute URL must be on the API host's full origin: same scheme, host and effective port, and no userinfo at all. Bare ids are unaffected; a link read from aparentenvelope gets the plain-path rule but is never confined to a family or a version. See Rust API — Ids, paths, URLs andparent. -
update_scheduleanddelete_schedulerefuse a bare schedule id (field: "schedule"): a pause lives under a network and a profile these methods are not given. Pass the pause's own path or URL (exactly/<version>/networks/{id}/profiles/{id}/schedules/{id}) or its envelope asparent.
Sessions, storage and the cache
-
Verified saves.
FileStore,KeyringStoreandChainedStoreread the record back after everysaveand returnOk(())only if the token is there. A write the backend accepted but did not keep is the newStorageError::NotRetained { backend }, so underStorageFailures::Fatala keyring that silently drops writes is now anError::Storagewhere 2.x succeeded. Under the defaultWarn, checkcredentials_persisted().ChainedStorefalls back unless the primary write is verified, retires a fallback record only when it is its own, and logs a fixedWARNwhenclearleaves a backend uncleared. See Configuration — Credential stores. -
A session change resets the
Client.set_session_token,clear_session_tokenandlogoutempty the cache and forget a preferred network that auto-discovery chose, so the next call without anetwork_idrediscovers the new account's network. A network set withset_preferred_networksurvives them; the newClient::clear_auth_datadrops it too. - Cache details. A cached getter whose request was overtaken by an invalidation no longer writes the pre-write answer back; a device's entry is keyed by its canonical MAC, so any spelling hits it; expired entries are dropped when read. See Rust API — Caching.
Logging and deprecations
-
No transport
WARNorERRORline carries a request URL, a path or a query string, and their wording followseero-api(Request timed out on GET request,Network error (connect) on GET request,Retrying GET request after transient failure (attempt 2/2), …). The path appears atDEBUGonly. Update any alerting that matched the old text. See Configuration — Logging and redaction. -
redact_sensitivewalks a top-level array and replaces anything nested 16 levels deep or more with[REDACTED:cyclic-or-too-deep]. -
NetworksApi::get_accountis deprecated in favour ofAccountApi::get_account(client.api().account().get_account()); the wire request is the sameGET /2.2/account.Client::get_accountand theget_networks()fallback already use the new one.
-
Clientwrappers (each with the domain method behind it):ClientmethodRequest get_eeros_data_usage(start, end, cadence, timezone, timeout, nid)GET networks/{id}/data_usage/eerosadd_to_blacklist(mac, nid, parent)POST networks/{id}/blacklist, formmac=<mac>(verified)remove_from_blacklist(mac_or_device_id, nid, parent)DELETE networks/{id}/blacklist/{mac}(verified)create_burst_reporter(nid, parent)POST networks/{id}/burst_reporters, body""(verified)reboot_network(nid, parent)POST networks/{id}/reboot, body""; restarts every eeroset_hide_5g(enabled, nid)PUT {"value": true}or a body-lessDELETEtonetworks/{id}/temporary_flags/hide_5gset_preferred_update_hour(hour, nid)POST networks/{id}/updates/preferred_update_hour,{"preferred_update_hour": hour},hourin0..=23set_ipv6_upstream(enabled, nid, parent)PUT {"ipv6_upstream": enabled}to the network's settings linkset_network_ad_block(enabled, profiles, nid, parent)POST networks/{id}/dns_policies/adblock,{"enable": enabled}plus"profiles"when given (premium)set_network_block_malware(enabled, nid, parent)POST networks/{id}/dns_policies/network,{"block_malware": enabled}(premium)request_support(request_data, nid, parent)JSON POSTofrequest_datato the network's support linkset_weekday_bedtime(profile_id, start_time, end_time, nid, parent)/set_weekend_bedtime(..)Create one Bedtime pause on the profile, Monday to Friday / Saturday and Sunday clear_auth_data()No request: clears the session and the store, the cache and any preferred network credentials_persisted()No request: whether the most recent save reached the store and was kept None of these auto-discovers the network. The wrappers that take
parentforward yours, and otherwise pass the cached network envelope (the profile's envelope for the bedtime helpers, with no cache fallback). -
Domain methods:
AccountApi::get_account(GET /2.2/account),NetworksApi::set_hide_5g(network_id, enabled),UpdatesApi::set_preferred_update_hour(network_id, hour),SecurityApi::set_ipv6_upstream(network_id, enabled, parent),DnsPoliciesApi::set_network_ad_block(network_id, enabled, profiles, parent)andset_network_block_malware(network_id, enabled, parent),DataUsageApi::get_eeros_usage(network_id, start, end, cadence, timezone, timeout, parent). Onlyadd_to_blacklist,remove_from_blacklistandcreate_burst_reporteramong the writes are verified; the rest log the uncharacterised-write warning. -
Timeouts:
rusteero::RequestTimeout { total, read }(new,total,Default) andTransport::{request, resource, nested}_with_timeout. -
Sessions and storage:
credentials_persisted()onClient,EeroApi,AuthApiandTransport;Transport::set_session_async;StorageError::NotRetained { backend };KeyringStore::warn_on_unpersisted(bool); the publicrusteero::storage::{load_async, save_async, clear_async}adapters. -
Links and validation:
rewrite_version(also at the crate root),links::require_family_path,links::origin_mismatchwithOriginMismatchand theORIGIN_*reason constants,params::require_non_empty_string,params::require_hour. -
Constants:
consts::LEGACY_USER_AGENT,consts::RETRY_AFTER_MAX,endpoints::dhcp::{DHCP_MODE_AUTOMATIC, DHCP_MODE_MANUAL, DHCP_MODE_CUSTOM}, and the route constants for the new endpoints (routes::networks::NETWORKS_SET_HIDE_5G, …). -
Transport::user_agent()returns the effectiveUser-Agent.
There is still no close(): dropping a Client releases its connection pool, and there is no
closed state to re-enter.
- Grep for
Error::Authentication {andError::RateLimit {— addstatusor..; build local auth errors withError::authentication(..). - Grep for
.status()on errors —AuthenticationandRateLimitnow returnSome(..). - Grep for the nine data-usage reads — add
None(or aRequestTimeout) beforenetwork_id/parent. - Grep for
set_session_token(,clear_session_token(,clear_auth_data(— add.await, and build with-D warningsso a forgotten one is an error. - Grep for
create_burst_reporter(— passNone, or switch toclient.create_burst_reporter(nid, parent). - Decide on the
User-Agent: keep the new default, or passconsts::LEGACY_USER_AGENT. - Grep for
field == "link","user_agent"andbase_urlmessage matches — switch to the new field names and fixed messages. - Grep for
update_schedule(/delete_schedule(with a bare id — pass the pause's path, URL or envelope. - Grep for
set_dhcp(Some("manual")— it now takes effect as"custom", and restarts the mesh. - Grep for
TransportBuilder::timeout(Duration::ZERO)/read_timeout(Duration::ZERO)— now unbounded. - Grep for
networks().get_account(— useaccount().get_account(). - Under
StorageFailures::Warn, checkcredentials_persisted()after a session change if persistence matters to you. - Update log alerting that matched a transport
WARN/ERRORline or expected a URL in it.
What broke: five groups of changes landed together.
- Surface that never worked against the current API, or that the API stopped serving, is gone — Removed.
- Several writes were re-pointed to the request forms the API declares, with new signatures — Changed signatures.
-
Errorvariants changed shape, and three previously-unused variants (plus two new ones) are now raised — Errors. - The session transport, credential record and refresh flow changed — Session, transport and storage.
- Fourteen domain modules were added, every resource argument became id-or-URL polymorphic,
and every domain method whose Python counterpart takes
parent=gained it — Added.
There is no deprecation window: a removed method is a compile error, not a runtime no-op.
| Removed in 2.0.0 | If you called it | Do this instead |
|---|---|---|
Client::get_settings, EeroApi::settings(), endpoints::SettingsApi
|
Replace with a network read |
client.get_network(nid, false) — the same fields live on the network envelope |
Client::get_password, EeroApi::password(), endpoints::PasswordApi
|
Replace with a network read | client.get_network(nid, false) |
Client::set_ipv6_dns |
It toggled ipv6_upstream, never DNS servers |
client.set_ipv6(enabled, nid) for the connectivity toggle; client.set_custom_dns_ipv6(servers, nid) for IPv6 DNS servers |
Client::run_insights |
Remove — the API has no such operation | None |
Client::run_ouicheck |
Remove — the API has no such operation | None |
SecurityApi::set_thread; the thread argument of configure_security
|
Remove — the settings write ignores a thread field |
client.set_thread_enabled(enabled, nid) (now a JSON PUT to networks/{id}/thread), update_thread(..), regenerate_thread_credentials(nid)
|
Client::set_sqm_enabled, set_sqm_bandwidth, configure_sqm, set_sqm_auto
|
They sent bandwidth/mode fields the API never declared |
client.set_sqm(enabled, nid) — a single toggle, sent as the sqm query parameter. Settings-class: may reboot the mesh |
Client::get_backup_network, get_backup_status, set_backup_network, configure_backup_network
|
Fields (phone_number) the API never declared |
client.get_backup_internet(nid), set_backup_internet(enabled, nid), get_cellular_backup_usage(nid), get_cellular_backup_events(nid)
|
Client::get_profile_schedule, set_profile_schedule
|
They wrote a schedule array onto the profile — not a profile field |
Schedules are sub-resources: get_schedules(profile_id, nid), create_schedule(profile_id, name, days, start, end, enabled, nid), update_schedule(schedule, &options, parent), delete_schedule(schedule, parent)
|
Client::get_blocked_applications, set_blocked_applications, update_profile_content_filter, update_profile_block_list
|
They wrote fields a profile does not have — silent no-ops | The DNS-policies family: block_domain_for_profiles(domain, profiles, is_delete, override_, nid), set_profile_blocked_applications(profile_id, applications, nid), get_dns_policy_applications(profile_id, nid)
|
Client::get_burst_reporters |
Remove — the endpoint returns 404 | None; the resource is POST-only. In 2.x: client.api().burst_reporters().create_burst_reporter(network_id, reporter_data, parent); from 3.0.0: client.create_burst_reporter(nid, parent)
|
Client::create_burst_reporter, Client::request_support, Client::reboot_network
|
Wrappers the Python facade did not have at 8.0.4 (it gained them by 8.4.1, and 3.0.0 restores them) | In 2.x: client.api().burst_reporters().create_burst_reporter(..), client.api().support().request_support(network_id, request_data, parent), client.api().networks().reboot_network(network_id, parent). From 3.0.0: client.create_burst_reporter(nid, parent), client.request_support(request_data, nid, parent), client.reboot_network(nid, parent)
|
Client::add_to_blacklist, Client::remove_from_blacklist
|
Use the device-level pair (3.0.0 restores both as (mac, nid, parent)) |
client.block_device(device_id, nid) / client.unblock_device(device_id, nid); the domain methods client.api().blacklist().add_to_blacklist / remove_from_blacklist remain |
consts::MAX_ERROR_BODY_CHARS |
Error messages no longer embed a body | Read Error::envelope()
|
routes::Route (the 1.0.0 route model) |
Transport-level only |
routes::Resource / routes::Nested; Transport::request(method, url, query, body) for a raw call |
// Before (1.0.0)
client.set_sqm_enabled(true, None).await?;
client.get_settings(None).await?;
client.set_ipv6_dns(true, None).await?;
// After (2.0.0) — read first; set_sqm is a settings-class write
let net = client.get_network(None, false).await?;
if net.data()["sqm"] != serde_json::json!(true) {
client.set_sqm(true, None).await?;
}
client.set_ipv6(true, None).await?; // connectivity toggle
client.set_custom_dns_ipv6(&["2001:4860:4860::8888"], None).await?; // IPv6 DNS servers| Method | 1.0.0 | 2.0.0 |
|---|---|---|
block_device |
(device_id, blocked: bool, nid) — one method for both directions |
block_device(device_id, nid) posts device_id as the form field mac to POST networks/{id}/blacklist, so pass the device's MAC; unblock_device(device_id, nid) is DELETE networks/{id}/blacklist/{mac}. Both are verified live (block_device since 3.0.0, which dropped its warning) |
set_guest_network |
(enabled, name, password, nid) — one JSON PUT carrying the password |
(enabled, name: Option<&str>, nid) — form-encoded PUT to the guestnetwork link. password is gone: set_guest_password(password, nid) / clear_guest_password(nid). All three verified live |
set_nightlight |
(eero_id, enabled, brightness, schedule_enabled, schedule_on, schedule_off, ambient_light_enabled, nid) |
(eero_id, enabled: Option<bool>, brightness_percentage: Option<i32>, schedule: Option<Value>, nid) — JSON PUT to the nightlight sub-resource with only the fields the API declares; FeatureUnavailable on an eero without a nightlight |
set_nightlight_schedule |
(eero_id, enabled, on_time, off_time, nid) |
(eero_id, schedule: Value, nid) — the schedule object is forwarded unchanged |
set_nightlight_brightness |
(eero_id, brightness, nid) |
Same positions; the parameter is brightness_percentage
|
set_led, set_led_brightness
|
JSON PUT to the eero's own URL — the 1.0.0 write was verified to change nothing | Same signatures; form-encoded led_on= / led_brightness= PUT to the led_action link, verified live. Any logic built on the old write has never actually run |
get_data_usage |
(nid, payload: Option<Value>, resource: Option<&str>) |
(start, end, cadence, timezone: Option<&str>, nid) — query parameters only; cadence is "daily" or "hourly". Each former resource value is an explicit method: get_data_usage_breakdown, get_devices_data_usage, get_device_data_usage, get_eeros_data_usage_summary, get_eero_data_usage, get_profile_data_usage, get_unprofiled_devices_data_usage, get_unprofiled_data_usage_summary, get_data_usage_report_settings, set_data_usage_report_settings
|
get_ouicheck |
(nid) — always 404'd |
(serial, version, nid) — both required; take them from the eero's own envelope |
get_insights |
(nid, start, end, insight_type, cadence) |
(start, end, insight_type, cadence, nid) — network_id moved last; five per-resource variants added |
run_diagnostics |
(nid) — empty POST |
(nid, device: Option<&str>, symptom: Option<&str>) — JSON POST of whichever you supply |
clear_custom_dns |
(nid) |
(family: Option<&str>, nid) — None, "ipv4" or "ipv6"; retains the stored servers |
create_profile |
(name, nid) |
(name, devices: Option<&[&str]>, paused: Option<bool>, nid) |
get_devices |
(nid, refresh_cache) |
(nid, refresh_cache, thread: Option<bool>, proxied_node: Option<bool>) — a filtered call bypasses the cache |
get_eero |
(eero_id, nid) |
(eero_id, nid, refresh_cache) — accepted for parity, never cached |
delete_reservation |
(reservation_id, nid) |
(reservation_id, delete_forwards: Option<bool>, nid) |
clear_profile_schedule |
-> Result<Envelope, Error> |
-> Result<Vec<Envelope>, Error> — one DELETE per pause |
configure_security |
(wpa3, band_steering, upnp, ipv6, thread, nid) |
(wpa3, band_steering, upnp, ipv6, nid) |
logout (Client, EeroApi, AuthApi) |
-> Result<Envelope, Error> |
-> Result<bool, Error>: false with no network call when not authenticated, else true; a failed request is logged, never propagated |
DNS writers (set_custom_dns, set_dns_mode, set_dns_caching, clear_custom_dns) |
Sent a custom_dns field the API does not have — no-ops |
Now take effect, and reboot every eero. Max 2 servers per family; provider presets ("cloudflare", …) are Error::Validation — read data.dns.default_test_servers. See Troubleshooting — DNS writes
|
// Before (1.0.0)
client.set_guest_network(true, Some("Guest"), Some("<password>"), None).await?;
client.block_device("<device-id>", true, None).await?;
client.block_device("<device-id>", false, None).await?;
client.set_profile_schedule("<profile-id>", &time_blocks, None).await?;
client.get_data_usage(None, None, Some("network")).await?;
// After (2.0.0)
client.set_guest_network(true, Some("Guest"), None).await?;
client.set_guest_password("<password>", None).await?;
client.block_device("<device-id>", None).await?;
client.unblock_device("<device-id>", None).await?;
client.create_schedule("<profile-id>", "Bedtime", &["monday"], "22:00", "06:00", true, None).await?;
client.get_data_usage("2026-07-01T00:00:00Z", "2026-07-21T00:00:00Z", "daily", None, None).await?;Every server-driven variant now carries envelope: Option<Value> and error_code: Option<String>,
and messages are fixed catalogue labels rather than a truncated body. Pattern matches on the
old shapes will not compile:
| Response | 1.0.0 | 2.0.0 |
|---|---|---|
| Any 401 | Error::Authentication(String) |
Error::Authentication { message, envelope, error_code } |
| 429 | Error::RateLimit { retry_after } |
Error::RateLimit { message, retry_after, envelope, error_code }; also raised for error.rate.limit on any status |
| Any 404 | Error::Api { status: 404, .. } |
Error::NotFound { status, message, envelope, error_code } |
403 with error.access.denied
|
Error::Api { status: 403, .. } |
Error::AccessDenied { .. } (new); is_auth_error() is false
|
| 400 with a form-error string | Error::Api { status: 400, .. } |
Error::Validation { field: "request", envelope, error_code, .. } |
| Premium / feature-unavailable strings, any status | Error::Api |
Error::PremiumRequired { status: Option<u16>, .. } / Error::FeatureUnavailable { .. } — now actually raised |
error.app.version.blocked, any status |
Error::Api |
Error::ClientBlocked { .. } (new) |
| Everything else |
Error::Api { status, message, url } with the body pasted (truncated) into message
|
Error::Api { status, message, envelope, error_code, url }; message is the catalogue string or "unrecognised error string"
|
| Local validation | Error::Validation { field, message } |
Error::Validation { field, message, envelope: None, error_code: None } |
// Before (1.0.0)
Err(Error::Authentication(msg)) => eprintln!("{msg}"),
Err(Error::Api { status: 404, .. }) => ...,
Err(Error::Api { message, .. }) if message.contains("error.session.expired") => ...,
// After (2.0.0)
Err(Error::Authentication { error_code, .. }) if error_code.as_deref() == Some("error.session.expired") => ...,
Err(Error::NotFound { .. }) => ...,
Err(e) => { let group = rusteero::classify_error_code(e.error_code()); ... }New: Error::envelope(), Error::error_code(), Error::status(), the rusteero::errors
module with the catalogue (ErrorGroup, classify_error_code, message_for_error_code,
error_for_response, the *_ERRORS slices), and rusteero::{ErrorGroup, classify_error_code}
at the crate root.
What changes for a caller: usually nothing. LoginFlow/PendingLogin/Session::from_token/
Session::from_env, set_session_token, clear_session_token and is_authenticated keep their
shapes, and a stored 1.0.0 session keeps working after its record is migrated. Underneath:
| 1.0.0 | 2.0.0 |
|---|---|
Token sent as the s= cookie |
Sent as the X-User-Token header, plus the legacy Cookie: s=<token> while send_legacy_cookie(true) (default). Both withheld from any URL off the configured host, scheme and port |
login / verify / logout sent JSON |
Form-encoded bodies (login=, code=, and a field named Cookie carrying s=<token>). resend sends {}; refresh sends the literal JSON string ""
|
reqwest's default User-Agent
|
Accept: application/json, User-Agent: eero/3.0 (iPhone; iOS 17.0) and X-Accept-Language: en-US on every request (user_agent, accept_language builder options). 3.0.0 changes the default User-Agent; see above
|
Session carried a client-fabricated 30-day expiry and an optional refresh token; Session::expiry(), Session::refresh_token()
|
Session is a token only. Both accessors are gone; is_valid() / is_authenticated() mean "a token is present". Any "days remaining" logic has nothing to read |
refresh_session looked for a refresh token the API never issues, falling back to account/refresh
|
POST /2.2/login/refresh authenticated by the session token itself; concurrent callers share one in-flight refresh; the server-issued token is ignored. A terminal 401 from the refresh endpoint clears the stored credential unless it carries a verification or error.session.refresh string |
PendingLogin::verify read a fresh Set-Cookie if the server sent one |
The login token becomes the session token; the verify response body is not consulted |
Stored record {"session_id", "refresh_token", "session_expiry"} (plus the legacy user_token read alias) |
{"session_id": "…", "schema_version": 2}. A record without schema_version is migrated on first load (token kept, other fields dropped, re-saved, read back); the migration never fails the load |
ChainedStore fallback branch rarely reachable |
save genuinely falls through to the fallback when the primary fails, clearing the stale primary entry first |
| No GET retry |
get_retries(n) — bounded retry for GET on transport error / 5xx, never for writes, 4xx or 429
|
If something outside the library reads or writes the credential file, stop reading
session_expiryandrefresh_token; readsession_idonly, and write{"session_id": ..., "schema_version": 2}.
-
Fourteen domain modules on
EeroApi, each withClientwrappers:account,backup_access_points,ddns,dhcp,dns_policies,entitlements,events,members,notifications,permissions,power_saving,subnets,wan,wpa3— plus node/port actions, LED cycle, nightlight override and support reads oneeros, and MLO / fast transition / Passpoint / proxied nodes onsecurity. See Rust API — the 37 domain accessors. -
Id-or-URL polymorphism. Every resource argument also accepts the resource's API path or its
absolute API-host URL. Existing bare-id calls keep working; a URL on another host is
Error::Validation. -
parent: Option<&Value>(last parameter) on everyEeroApidomain method whoseeero-apicounterpart takesparent=.Clientpasses its cached network / eero / device envelopes automatically — so a network-scoped call made while a freshget_network()result is cached goes to the link the API published, which may be on a different version than the method's template. (3.0.0 pins a few methods to one version whatever the link says; see Rust API —parent.) - The link helpers at the crate root:
resolve_link,self_url,resource_url,sub_resource_url,join_api_path;rusteero::params(validate_cadence,resolve_network_url,resolve_nested_url);rusteero::links::warn_uncharacterised_write. -
ClientBuilder::accept_language,send_legacy_cookie,get_retries. - On
Client:get_device_priority,update_device_via_link,set_device_type,get_device_labels,set_device_labels,set_location,get_connections,get_speed_tests,get_guest_network,set_network_password,clear_network_password,apply_update,update_forward,update_thread,regenerate_thread_credentials,set_custom_dns_ipv4,set_custom_dns_ipv6, the five per-resource insights reads and the data-usage family. -
consts::API_HOST,api_endpoint(version),API_VERSION_DEFAULT,API_VERSION_DEVICE_WRITES,API_VERSION_MULTISTATICIP,API_VERSION_SECONDARY_WAN,DEFAULT_USER_AGENT,DEFAULT_ACCEPT_LANGUAGE,GET_RETRY_DELAY,CREDENTIAL_SCHEMA_VERSION,SESSION_REFRESH_GUARD_TIMEOUT,LOGOUT_COOKIE_FIELD_NAME,SESSION_COOKIE_PREFIX. -
transport::RequestBody(None,Json,Form,EmptyJsonString) andTransport::request/resource/nested.
- Grep for
get_settings(,get_password(,.settings(),.password()— replace withget_network. - Grep for
set_ipv6_dns(— split intoset_ipv6and/orset_custom_dns_ipv6. - Grep for
run_insights(,run_ouicheck(,get_burst_reporters(— remove. - Grep for
set_thread(andconfigure_security(with athreadargument — drop it;set_thread_enabledstill exists but is now a different, unverified write. - Grep for
set_sqm_enabled(,configure_sqm(,set_sqm_bandwidth(,set_sqm_auto(— replace withset_sqmbehind a read-compare-skip. - Grep for
get_backup_network(,get_backup_status(,set_backup_network(,configure_backup_network(— replace with the*_backup_internet/cellular_backupmethods. - Grep for
get_profile_schedule(,set_profile_schedule(,time_blocks— move to the schedule sub-resource methods; handleclear_profile_schedule'sVec<Envelope>. - Grep for
update_profile_content_filter(,update_profile_block_list(,get_blocked_applications(,set_blocked_applications(— move to the DNS-policies family (premium). - Grep for
set_guest_network(with a password — split intoset_guest_network+set_guest_password. - Grep for
block_device(with abool— split intoblock_device/unblock_device;add_to_blacklist(/remove_from_blacklist(onClient— same in 2.x (3.0.0 brings them back with a(mac, nid, parent)signature). - Grep for
set_nightlight(,set_nightlight_schedule(— switch tobrightness_percentage/schedule: Value. - Grep for
set_led(,set_led_brightness(— audit: the 1.0.0 write did nothing, so any behaviour that assumed the LED changed has never run. - Grep for
get_data_usage(— passstart,end,cadence; move per-resource reads to the explicit methods.get_ouicheck(— passserial,version.get_insights(—network_idis now last. - Grep for
run_diagnostics(,clear_custom_dns(,create_profile(,get_devices(,get_eero(,delete_reservation(— add the new arguments. - Grep for
Error::Authentication(,RateLimit {,Api {patterns — update to the new field sets; addNotFound,AccessDenied,Validationarms where you matched onstatus. - Grep for
.contains("error.on an error message — switch toerror_code()/classify_error_code. - Grep for
expiry(),refresh_token(),session_expiry,MAX_ERROR_BODY_CHARS— remove. -
logout()now returnsbool— drop anyEnvelopehandling on it. - Audit every DNS write call site: they now take effect and reboot every eero.
- Any automation issuing a settings-class write (
set_sqm,set_dhcp,set_connection_mode,set_nat_port_randomization,set_mlo_mode, the security setters,set_wpa3_per_band,set_power_saving,set_subnets_config,set_multistaticip, secondary WAN, the DNS writes) must read, compare and skip.
-
Pin a major version (
rusteero = "3") or a git tag, never the default branch — this crate follows an undocumented, reverse-engineered API, and breaking changes ship as majors on purpose. -
Read
CHANGELOG.mdfor every major between your pin and the target, and apply each section above in order (2.x → 3.0.0 assumes you have already done 1.0.0 → 2.0.0). -
Let the compiler find breakage: every removed or re-signatured method is a compile error,
not a runtime no-op. What it cannot catch:
- in 3.0.0, a session setter called as a bare statement without
.await(a warning only), a deprecatedSome(..)passed asreporter_data, and every item under Behaviour changes, the newUser-Agentfirst; - in 2.0.0, the DNS writers and
set_led/set_led_brightness(same names, now effective).
- in 3.0.0, a session setter called as a bare statement without
- 📖 Rust API — the full 3.0.0 surface
- ⚙️ Configuration — the schema-2 credential record and its migration
- 🔧 Troubleshooting — the DNS write path in detail
- 🏠 Home