use crate::error::Error;
use reqwest::Method;
use serde_json::Value;
use url::Url;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ApiVersion {
V2_2,
V2_3,
}
impl ApiVersion {
#[must_use]
pub const fn segment(self) -> &'static str {
match self {
Self::V2_2 => crate::consts::API_VERSION_DEFAULT,
Self::V2_3 => crate::consts::API_VERSION_DEVICE_WRITES,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Resource {
pub method: Method,
pub version: ApiVersion,
pub template: &'static str,
pub link: Option<&'static str>,
}
impl Resource {
pub fn resolve(
&self,
host: &Url,
id_or_url: &str,
parent: Option<&Value>,
) -> Result<Url, Error> {
if !self.template.contains("{id}") {
let base = host.as_str().trim_end_matches('/');
let segment = self.version.segment();
let path = self.template.trim_matches('/');
let full = format!("{base}/{segment}/{path}");
return Url::parse(&full)
.map_err(|err| Error::validation("url", format!("not a valid URL: {err}")));
}
match self.link {
Some(link) => crate::links::sub_resource_url(
host,
id_or_url,
self.template,
link,
parent,
self.version,
),
None => crate::links::resource_url(host, id_or_url, self.template, self.version),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Nested {
pub method: Method,
pub version: ApiVersion,
pub prefix: &'static str,
pub suffix: &'static str,
pub link: Option<&'static str>,
}
impl Nested {
pub fn resolve(
&self,
host: &Url,
network: &str,
child: &str,
parent: Option<&Value>,
) -> Result<Url, Error> {
crate::params::resolve_nested_url(
host,
network,
child,
self.prefix,
self.suffix,
self.link,
parent,
self.version,
)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SegmentError {
Empty,
ControlCharacter,
DotSegment,
}
impl std::fmt::Display for SegmentError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Empty => write!(f, "must not be empty"),
Self::ControlCharacter => {
write!(f, "must not contain an ASCII control character")
}
Self::DotSegment => write!(f, "must not be a \".\" or \"..\" path segment"),
}
}
}
impl std::error::Error for SegmentError {}
pub(crate) fn validate_segment(value: &str) -> Result<(), SegmentError> {
if value.is_empty() {
return Err(SegmentError::Empty);
}
if value.bytes().any(|b| matches!(b, 0x00..=0x1F | 0x7F)) {
return Err(SegmentError::ControlCharacter);
}
let stripped: String = value
.chars()
.filter(|&c| c != '\t' && c != '\r' && c != '\n')
.collect();
if stripped == "." || stripped == ".." {
return Err(SegmentError::DotSegment);
}
Ok(())
}
pub mod ac_compat;
pub mod account;
pub mod auth;
pub mod backup;
pub mod backup_access_points;
pub mod blacklist;
pub mod burst_reporters;
pub mod data_usage;
pub mod ddns;
pub mod devices;
pub mod dhcp;
pub mod diagnostics;
pub mod dns;
pub mod dns_policies;
pub mod eeros;
pub mod entitlements;
pub mod events;
pub mod forwards;
pub mod insights;
pub mod members;
pub mod networks;
pub mod notifications;
pub mod ouicheck;
pub mod permissions;
pub mod power_saving;
pub mod profiles;
pub mod reservations;
pub mod routing;
pub mod schedule;
pub mod security;
pub mod sqm;
pub mod subnets;
pub mod support;
pub mod thread;
pub mod transfer;
pub mod updates;
pub mod wan;
pub mod wpa3;
pub use ac_compat::*;
pub use account::*;
pub use auth::*;
pub use backup::*;
pub use backup_access_points::*;
pub use blacklist::*;
pub use burst_reporters::*;
pub use data_usage::*;
pub use ddns::*;
pub use devices::*;
pub use dhcp::*;
pub use diagnostics::*;
pub use dns::*;
pub use dns_policies::*;
pub use eeros::*;
pub use entitlements::*;
pub use events::*;
pub use forwards::*;
pub use insights::*;
pub use members::*;
pub use networks::*;
pub use notifications::*;
#[allow(unused_imports)]
pub use ouicheck::*;
pub use permissions::*;
pub use power_saving::*;
pub use profiles::*;
pub use reservations::*;
pub use routing::*;
pub use schedule::*;
pub use security::*;
pub use sqm::*;
pub use subnets::*;
pub use support::*;
pub use thread::*;
pub use transfer::*;
pub use updates::*;
pub use wan::*;
pub use wpa3::*;
#[cfg(test)]
mod tests {
use super::ApiVersion;
use reqwest::Method;
#[test]
fn required_auth_and_account_routes_have_the_expected_verb_version_and_template() {
use super::{ACCOUNT, LOGIN, LOGIN_REFRESH, LOGIN_RESEND, LOGIN_VERIFY, LOGOUT};
assert_eq!(LOGIN.method, Method::POST);
assert_eq!(LOGIN.version, ApiVersion::V2_2);
assert_eq!(LOGIN.template, "login");
assert_eq!(LOGIN_VERIFY.method, Method::POST);
assert_eq!(LOGIN_VERIFY.version, ApiVersion::V2_2);
assert_eq!(LOGIN_VERIFY.template, "login/verify");
assert_eq!(LOGIN_RESEND.method, Method::POST);
assert_eq!(LOGIN_RESEND.version, ApiVersion::V2_2);
assert_eq!(LOGIN_RESEND.template, "login/resend");
assert_eq!(LOGOUT.method, Method::POST);
assert_eq!(LOGOUT.version, ApiVersion::V2_2);
assert_eq!(LOGOUT.template, "logout");
assert_eq!(LOGIN_REFRESH.method, Method::POST);
assert_eq!(LOGIN_REFRESH.version, ApiVersion::V2_2);
assert_eq!(LOGIN_REFRESH.template, "login/refresh");
assert_eq!(ACCOUNT.method, Method::GET);
assert_eq!(ACCOUNT.version, ApiVersion::V2_2);
assert_eq!(ACCOUNT.template, "account");
}
#[test]
fn login_and_verify_resolve_to_the_expected_absolute_urls() {
use super::{LOGIN, LOGIN_VERIFY};
use url::Url;
let host = Url::parse("http://mock.test:1234").unwrap();
assert_eq!(
LOGIN.resolve(&host, "", None).unwrap().as_str(),
"http://mock.test:1234/2.2/login"
);
assert_eq!(
LOGIN_VERIFY.resolve(&host, "", None).unwrap().as_str(),
"http://mock.test:1234/2.2/login/verify"
);
}
use super::{SegmentError, validate_segment};
#[test]
fn validate_segment_rejects_empty_value() {
assert_eq!(validate_segment(""), Err(SegmentError::Empty));
}
#[test]
fn validate_segment_rejects_control_characters() {
assert_eq!(
validate_segment("..\n"),
Err(SegmentError::ControlCharacter)
);
assert_eq!(
validate_segment(".\t."),
Err(SegmentError::ControlCharacter)
);
assert_eq!(
validate_segment("\t.."),
Err(SegmentError::ControlCharacter)
);
assert_eq!(
validate_segment("..\t"),
Err(SegmentError::ControlCharacter)
);
assert_eq!(
validate_segment("..\r\n"),
Err(SegmentError::ControlCharacter)
);
assert_eq!(
validate_segment("\u{0}"),
Err(SegmentError::ControlCharacter)
);
assert_eq!(
validate_segment("a\u{7f}b"),
Err(SegmentError::ControlCharacter)
);
}
#[test]
fn validate_segment_rejects_literal_dot_segments() {
assert_eq!(validate_segment("."), Err(SegmentError::DotSegment));
assert_eq!(validate_segment(".."), Err(SegmentError::DotSegment));
}
#[test]
fn validate_segment_accepts_legitimate_and_already_safe_values() {
for value in [
"device-0001",
"aa:bb:cc:00:00:01",
"a/b",
"%2e%2e",
"..%2f..",
"..", "a?b",
"a#b",
] {
assert_eq!(
validate_segment(value),
Ok(()),
"value {value:?} must be accepted"
);
}
}
use super::{Nested, Resource};
use url::Url;
fn fake_host() -> Url {
Url::parse("http://mock.test:1234").unwrap()
}
#[test]
fn resource_with_placeholder_resolves_bare_id_against_its_version() {
let resource = Resource {
method: Method::GET,
version: ApiVersion::V2_2,
template: "networks/{id}",
link: None,
};
let url = resource.resolve(&fake_host(), "100", None).unwrap();
assert_eq!(url.as_str(), "http://mock.test:1234/2.2/networks/100");
}
#[test]
fn resource_without_placeholder_resolves_a_fixed_path_and_ignores_id_or_url() {
let resource = Resource {
method: Method::GET,
version: ApiVersion::V2_2,
template: "account",
link: None,
};
let url = resource.resolve(&fake_host(), "ignored", None).unwrap();
assert_eq!(url.as_str(), "http://mock.test:1234/2.2/account");
}
#[test]
fn resource_with_link_prefers_the_parents_published_link() {
let resource = Resource {
method: Method::PUT,
version: ApiVersion::V2_2,
template: "networks/{id}/settings",
link: Some("settings"),
};
let parent = serde_json::json!({"resources": {"settings": "/2.4/networks/100/settings"}});
let url = resource
.resolve(&fake_host(), "100", Some(&parent))
.unwrap();
assert_eq!(
url.as_str(),
"http://mock.test:1234/2.4/networks/100/settings"
);
}
#[test]
fn resource_with_link_falls_back_when_no_parent_supplied() {
let resource = Resource {
method: Method::PUT,
version: ApiVersion::V2_2,
template: "networks/{id}/settings",
link: Some("settings"),
};
let url = resource.resolve(&fake_host(), "100", None).unwrap();
assert_eq!(
url.as_str(),
"http://mock.test:1234/2.2/networks/100/settings"
);
}
#[test]
fn nested_resolves_bare_child_id() {
let nested = Nested {
method: Method::GET,
version: ApiVersion::V2_2,
prefix: "profiles",
suffix: "",
link: None,
};
let url = nested.resolve(&fake_host(), "100", "p1", None).unwrap();
assert_eq!(
url.as_str(),
"http://mock.test:1234/2.2/networks/100/profiles/p1"
);
}
#[test]
fn nested_with_link_prefers_the_parents_published_link() {
let nested = Nested {
method: Method::GET,
version: ApiVersion::V2_2,
prefix: "profiles",
suffix: "/schedules",
link: Some("schedules"),
};
let parent = serde_json::json!({"resources": {"schedules": "/2.5/networks/100/profiles/p1/schedules"}});
let url = nested
.resolve(&fake_host(), "100", "p1", Some(&parent))
.unwrap();
assert_eq!(
url.as_str(),
"http://mock.test:1234/2.5/networks/100/profiles/p1/schedules"
);
}
fn settings_resource() -> Resource {
Resource {
method: Method::PUT,
version: ApiVersion::V2_2,
template: "networks/{id}/settings",
link: Some("settings"),
}
}
#[test]
fn resource_accepts_a_path_or_url_in_its_family_and_keeps_the_callers_version() {
let resource = settings_resource();
for supplied in [
"/2.3/networks/100",
"/2.3/networks/100/",
"http://mock.test:1234/2.3/networks/100",
] {
let url = resource.resolve(&fake_host(), supplied, None).unwrap();
assert_eq!(
url.as_str(),
"http://mock.test:1234/2.3/networks/100/settings",
"{supplied}"
);
}
}
#[test]
fn resource_rejects_a_path_or_url_from_another_family() {
let resource = settings_resource();
for supplied in [
"/2.2/account",
"/2.2/eeros/9",
"/2.2/networks/100/devices",
"/2.2/networks/100//",
"/2.2/networks/../account",
"/2.2/networks/%2e%2e/account",
"/2.2/networks/100?x=1",
"/2.2/networks/100\n",
"http://mock.test:1234/2.2/account",
"https://api-user.e2ro.com/2.3/networks/100",
] {
let err = resource.resolve(&fake_host(), supplied, None).unwrap_err();
assert!(
matches!(err, crate::error::Error::Validation { .. }),
"{supplied:?}"
);
}
}
#[test]
fn resource_does_not_confine_the_parents_published_link() {
let parent = serde_json::json!({"resources": {"settings": "/2.4/account/other"}});
let url = settings_resource()
.resolve(&fake_host(), "100", Some(&parent))
.unwrap();
assert_eq!(url.as_str(), "http://mock.test:1234/2.4/account/other");
}
#[test]
fn nested_accepts_only_a_child_under_the_addressed_networks_collection() {
let nested = Nested {
method: Method::DELETE,
version: ApiVersion::V2_2,
prefix: "profiles",
suffix: "",
link: None,
};
let url = nested
.resolve(&fake_host(), "100", "/2.2/networks/100/profiles/p1/", None)
.unwrap();
assert_eq!(
url.as_str(),
"http://mock.test:1234/2.2/networks/100/profiles/p1"
);
for child in [
"/2.2/networks/200/profiles/p1",
"/2.2/networks/100/profiles/..",
"/2.2/networks/100/profiles/p1/../p2",
"/2.2/account",
"/2.2/networks/100/profiles",
] {
let err = nested
.resolve(&fake_host(), "100", child, None)
.unwrap_err();
assert!(
matches!(err, crate::error::Error::Validation { .. }),
"{child:?}"
);
}
}
}