//! Home Assistant HTTP 客户端与**端点选择**。 //! //! P0 只用到两件事:探测(`GET /api/` + `GET /api/config`)与端点选择 //! (`auto` / `local` / `remote` 三档)。设备数据与控制命令在 P1/P2 才接上来, //! 但它们**必须复用这里的 `resolve_endpoint`**,否则在外面的每次请求都会先等 //! 局域网超时。 //! //! 超时策略见 `SMART_HOME_MODULE_PLAN.md` §3.7:局域网探测必须短(在外会必然耗满), //! 反代探测可以宽松(Cloudflare Tunnel 的 RTT 常在 100–400ms)。 use std::time::Instant; use serde::Deserialize; use serde_json::json; use crate::smarthome::types::{ EndpointKind, EndpointMode, EndpointProbe, EntitySummary, HaConnection, ServiceParams, }; /// 局域网探测超时(**必须短**)。 /// /// 在家里局域网必然 <10ms 命中;在外面,这个地址会因为 ARP / 路由不可达而 /// **必然耗满超时**。它直接决定"出门后每次冷探测有多卡"。 pub const LOCAL_PROBE_TIMEOUT_MS: u64 = 900; /// 反代探测超时(Cloudflare Tunnel 首包可能较慢,给足余量)。 pub const REMOTE_PROBE_TIMEOUT_MS: u64 = 5000; /// 强制模式(`local` / `remote`)下的超时:此时失败就是"真的连不上", /// 不该因为 900ms 这种"用于探测缺失"的短超时把可用链路判死。 pub const FORCED_PROBE_TIMEOUT_MS: u64 = 5000; /// 「测试连接」在单个地址上的总超时(要跑两个请求,给比探测更宽的预算)。 pub const TEST_LOCAL_TIMEOUT_MS: u64 = 8000; pub const TEST_REMOTE_TIMEOUT_MS: u64 = 20000; /// 普通数据请求的超时:局域网 8s / 反代 30s。 /// /// 反代上 `/api/states` 是几百 KB(gzip 后几十 KB),这里给的是"能成功但慢"的余量, /// 不是"期望 30s" —— 实际体验主要由 §3.7 的链路选择与 gzip 决定。 pub const REQUEST_TIMEOUT_LOCAL_MS: u64 = 8000; pub const REQUEST_TIMEOUT_REMOTE_MS: u64 = 30000; /// 按链路取数据请求超时。 pub fn request_timeout(kind: EndpointKind) -> u64 { match kind { EndpointKind::Local => REQUEST_TIMEOUT_LOCAL_MS, EndpointKind::Remote => REQUEST_TIMEOUT_REMOTE_MS, } } /// 一次 HTTP 交互失败的分类结果(探测与数据/控制请求共用)。 #[derive(Debug, Clone)] pub struct ProbeFailure { /// auth | network | notFound | badRequest | server | other pub kind: &'static str, pub message: String, /// 是否属于"令牌本身无效"。 /// /// 这类失败**必须立刻放弃换端点重试**:同一个令牌在所有地址上都无效, /// 继续试反代只会让用户多等一个超时,并把真正的原因(令牌失效)淹没在 /// "都无法连接"里。 pub fatal_auth: bool, } impl ProbeFailure { fn auth(message: impl Into) -> Self { Self { kind: "auth", message: message.into(), fatal_auth: true, } } fn network(message: impl Into) -> Self { Self { kind: "network", message: message.into(), fatal_auth: false, } } fn server(message: impl Into) -> Self { Self { kind: "server", message: message.into(), fatal_auth: false, } } /// 实体 / 服务不存在(设备被移除、集成重载) fn not_found(message: impl Into) -> Self { Self { kind: "notFound", message: message.into(), fatal_auth: false, } } /// 参数不被该服务接受(如给不支持色温的灯传 `color_temp_kelvin`) fn bad_request(message: impl Into) -> Self { Self { kind: "badRequest", message: message.into(), fatal_auth: false, } } } /// 端点选择结果。 pub struct ResolvedEndpoint { pub url: String, pub kind: EndpointKind, pub latency_ms: u64, } /// 端点选择失败:带分类,前端据此决定是"重填令牌"还是"重试/切换地址"(§3.6)。 #[derive(Debug, Clone)] pub struct ResolveFailure { /// auth | network | config pub kind: &'static str, pub message: String, } impl ResolveFailure { fn new(kind: &'static str, message: impl Into) -> Self { Self { kind, message: message.into(), } } } /// 地址规范化:补协议(局域网默认 `http`、反代默认 `https`)、去掉结尾斜杠。 pub fn normalize_url(input: &str, prefer_https: bool) -> String { let mut u = input.trim().to_string(); if u.is_empty() { return u; } let lower = u.to_lowercase(); if !lower.starts_with("http://") && !lower.starts_with("https://") { u = if prefer_https { format!("https://{u}") } else { format!("http://{u}") }; } while u.ends_with('/') { u.pop(); } u } /// REST 端点 → WebSocket 端点:`http` → `ws`、`https` → `wss`,路径固定 `/api/websocket`。 /// /// **复用同一份端点选择结果**(plan §3.7-a 最后一条):WS 一旦连上就固定在所选端点, /// 不允许同一屏数据来自两条链路(否则"更新于 x 秒前"的时间戳会来自不同链路)。 pub fn ws_url(base: &str) -> Result { let mut u = url::Url::parse(base).map_err(|e| format!("HA 地址不合法:{e}"))?; let ok = match u.scheme() { "https" => u.set_scheme("wss").is_ok(), "http" => u.set_scheme("ws").is_ok(), "ws" | "wss" => true, other => return Err(format!("不支持用 {other} 建立 WebSocket 连接")), }; if !ok { return Err("无法把该地址转换成 WebSocket 协议".to_string()); } u.set_path("/api/websocket"); u.set_query(None); Ok(u.to_string()) } /// 校验地址合法性(保存时做,**不要在请求时才失败**——那时错误信息已经离用户输入很远了)。 pub fn validate_url(url: &str, label: &str) -> Result<(), String> { if url.trim().is_empty() { return Ok(()); } let parsed = url::Url::parse(url).map_err(|e| format!("{label}不是合法的地址:{e}"))?; if parsed.host_str().unwrap_or("").is_empty() { return Err(format!("{label}缺少主机名")); } Ok(()) } fn build_client(insecure: bool, timeout_ms: u64) -> Result { reqwest::Client::builder() // 自签证书:与飞牛连接同款开关。局域网 IP 的 HA 通常是 http,用不到它; // 反代若用 IP 直连 + 自签证书才需要。 .danger_accept_invalid_certs(insecure) .timeout(std::time::Duration::from_millis(timeout_ms)) // 压缩交给 reqwest 自动协商(Cargo.toml 已开 `gzip` feature): // 反代链路上 `/api/states` 是几百 KB JSON,不压缩就是白送 5–10 倍流量。 .build() .map_err(|e| format!("构建 HTTP 客户端失败:{e}")) } #[derive(Deserialize)] struct ApiRoot { #[serde(default)] message: String, } #[derive(Deserialize)] struct HaConfig { #[serde(default)] version: String, #[serde(default)] location_name: String, #[serde(default)] unit_system: UnitSystem, } /// HA 的系统单位制(`/api/config`)。只有温度是本模块需要的 —— /// climate 的 `temperature` / `min_temp` / `max_temp` 都按它给值。 #[derive(Deserialize, Default)] struct UnitSystem { #[serde(default)] temperature: String, } fn describe_request_error(e: &reqwest::Error) -> String { if e.is_timeout() { "连接超时".to_string() } else if e.is_connect() { "无法建立连接".to_string() } else { format!("请求失败:{e}") } } /// 轻量可达性检查:`GET /api/`(地址可达 + 令牌有效 + **确实是 HA 的 API**)。 /// 返回耗时(毫秒)。 /// /// 为什么要校验响应体而不仅是状态码:反代前面若挂了访问网关(如 Cloudflare Access), /// 未携带 Service Token 时会被重定向到一个 **200 的 HTML 登录页** —— 只看状态码会把它 /// 判成"链路正常",随后的真实请求才会莫名其妙地失败(§2.2-6)。 async fn check_reachable( base: &str, token: &str, insecure: bool, timeout_ms: u64, ) -> Result { let client = build_client(insecure, timeout_ms).map_err(ProbeFailure::network)?; let started = Instant::now(); let resp = client .get(format!("{base}/api/")) .bearer_auth(token) .send() .await .map_err(|e| ProbeFailure::network(describe_request_error(&e)))?; let status = resp.status(); if status.as_u16() == 401 || status.as_u16() == 403 { return Err(ProbeFailure::auth("访问令牌无效或已被吊销")); } if !status.is_success() { return Err(ProbeFailure::server(format!("HTTP {}", status.as_u16()))); } let root = resp.json::().await.map_err(|_| { ProbeFailure::server("响应不是 Home Assistant 的 API(可能被反向代理或访问网关拦截)") })?; if root.message.is_empty() { return Err(ProbeFailure::server("Home Assistant 返回了空响应")); } Ok(started.elapsed().as_millis() as u64) } /// 探测单个地址(「测试连接」用):`GET /api/` + `GET /api/config`。 /// /// 不拉 `/api/states` 统计实体数:那是几百 KB 的响应,在反代链路上会把 /// "测试连接"从 1 秒拖到 3 秒以上,而实体列表在 P1 本来就会拉一次。 pub async fn probe_url( url: &str, token: &str, insecure: bool, kind: EndpointKind, ) -> EndpointProbe { let timeout_ms = match kind { EndpointKind::Local => TEST_LOCAL_TIMEOUT_MS, EndpointKind::Remote => TEST_REMOTE_TIMEOUT_MS, }; let mut failure: Option = None; let started = Instant::now(); let mut ha_version = String::new(); let mut location_name = String::new(); let mut temperature_unit = String::new(); let mut ok = false; match check_reachable(url, token, insecure, timeout_ms).await { Ok(_) => match fetch_config(url, token, insecure, timeout_ms).await { Ok(cfg) => { ha_version = cfg.version; location_name = cfg.location_name; temperature_unit = cfg.unit_system.temperature; ok = true; } Err(e) => failure = Some(e), }, Err(e) => failure = Some(e), } EndpointProbe { url: url.to_string(), kind, ok, ha_version, location_name, temperature_unit, elapsed_ms: started.elapsed().as_millis() as u64, error: failure.as_ref().map(|f| f.message.clone()), error_kind: failure.as_ref().map(|f| f.kind.to_string()), } } async fn fetch_config( base: &str, token: &str, insecure: bool, timeout_ms: u64, ) -> Result { let client = build_client(insecure, timeout_ms).map_err(ProbeFailure::network)?; let resp = client .get(format!("{base}/api/config")) .bearer_auth(token) .send() .await .map_err(|e| ProbeFailure::network(describe_request_error(&e)))?; let status = resp.status(); if !status.is_success() { if status.as_u16() == 401 || status.as_u16() == 403 { return Err(ProbeFailure::auth("访问令牌无效或已被吊销")); } return Err(ProbeFailure::server(format!("HTTP {}", status.as_u16()))); } resp.json::() .await .map_err(|e| ProbeFailure::server(format!("响应解析失败:{e}"))) } /// 逐个地址探测(顺序:局域网 → 反代),供「测试连接」使用。 pub async fn probe_all( local_url: &str, remote_url: &str, token: &str, insecure: bool, ) -> Vec { let mut out = Vec::new(); if !local_url.trim().is_empty() { out.push(probe_url(local_url.trim(), token, insecure, EndpointKind::Local).await); } if !remote_url.trim().is_empty() { out.push(probe_url(remote_url.trim(), token, insecure, EndpointKind::Remote).await); } out } /// 候选端点列表:(地址, 类型, 探测超时),按尝试顺序排列。 fn candidates(conn: &HaConnection) -> Result, ResolveFailure> { let local = conn.local_candidate(); let remote = conn.remote_candidate(); match conn.endpoint_mode { EndpointMode::Local => match local { Some((u, _)) => Ok(vec![(u, EndpointKind::Local, FORCED_PROBE_TIMEOUT_MS)]), None => Err(ResolveFailure::new( "config", "当前连接未配置局域网地址(端点策略为「仅局域网」)", )), }, EndpointMode::Remote => match remote { Some((u, _)) => Ok(vec![(u, EndpointKind::Remote, FORCED_PROBE_TIMEOUT_MS)]), None => Err(ResolveFailure::new( "config", "当前连接未配置反代地址(端点策略为「仅反代」)", )), }, EndpointMode::Auto => { let mut v = Vec::new(); // 局域网优先:回家时能自动切回,代价是出门后每轮冷探测多花 900ms // (见 types::EndpointMode 的注释,这里刻意**不**把 lastOkUrl 排在最前)。 if let Some((u, k)) = local { v.push((u, k, LOCAL_PROBE_TIMEOUT_MS)); } if let Some((u, k)) = remote { v.push((u, k, REMOTE_PROBE_TIMEOUT_MS)); } if v.is_empty() { return Err(ResolveFailure::new("config", "该连接没有配置任何地址")); } Ok(v) } } } /// 按 `endpoint_mode` 顺序探测,返回第一个可用端点。 /// /// 失败时的错误信息**包含每个地址的尝试结果** —— 用户需要知道"是局域网不可达、 /// 还是反代也挂了",一个笼统的"连接失败"无法排障。 pub async fn resolve_endpoint( conn: &HaConnection, token: &str, ) -> Result { let list = candidates(conn)?; let mut failures: Vec = Vec::new(); for (url, kind, timeout_ms) in list { match check_reachable(url, token, conn.insecure, timeout_ms).await { Ok(latency_ms) => { return Ok(ResolvedEndpoint { url: url.to_string(), kind, latency_ms, }); } Err(f) => { // 令牌无效:换任何地址都是同一个结果,立即停止 if f.fatal_auth { return Err(ResolveFailure::new("auth", f.message)); } failures.push(format!("{}:{}", kind_label(kind), f.message)); crate::logger::log_warn( "smarthome", &format!("端点探测失败({} {}):{}", kind_label(kind), url, f.message), ); } } } Err(ResolveFailure::new( "network", format!("所有地址均不可达 —— {}", failures.join(";")), )) } pub fn kind_label(kind: EndpointKind) -> &'static str { match kind { EndpointKind::Local => "局域网", EndpointKind::Remote => "反代", } } /// 取 HA 元信息(版本 / 实例名 / 温度单位)。 /// /// 「检测链路」与"首次拉实体时还不知道实例信息"两个场景会用到它 —— /// 只是一个很小的 `/api/config` 请求,因此不塞进每次数据拉取里。 pub async fn fetch_meta( base: &str, token: &str, insecure: bool, kind: EndpointKind, ) -> Result<(String, String, String), ProbeFailure> { let cfg = fetch_config(base, token, insecure, request_timeout(kind)).await?; Ok((cfg.version, cfg.location_name, cfg.unit_system.temperature)) } // ============ 实体状态(P1) ============ /// HA 的原始状态对象(`/api/states` 的元素,也是 WS 里 `subscribe_entities` 的形态)。 /// /// P4 起 `ws.rs` 也要用:WS 的增量是**差量更新**,必须先把 attributes 合并回一份 /// 完整的原始对象,再转 `EntitySummary` —— 所以这里不再是 P1 的私有实现细节。 #[derive(Deserialize, Default, Clone)] pub struct RawState { #[serde(default)] pub entity_id: String, #[serde(default)] pub state: String, /// **故意不建结构体**:attributes 的字段集合随 domain 差异极大 /// (灯 / 窗帘 / 气候 / 媒体播放器各不相同),按需白名单取用才稳。 #[serde(default)] pub attributes: serde_json::Value, #[serde(default)] pub last_changed: String, } /// 拉取全量实体状态并转成精简结构。 /// /// 调用方必须先 `resolve_endpoint` 拿到可用的 `base` 与 `kind` —— 这里不做链路选择。 pub async fn fetch_entities( base: &str, token: &str, insecure: bool, kind: EndpointKind, ) -> Result, ProbeFailure> { let client = build_client(insecure, request_timeout(kind)).map_err(ProbeFailure::network)?; let resp = client .get(format!("{base}/api/states")) .bearer_auth(token) .send() .await .map_err(|e| ProbeFailure::network(describe_request_error(&e)))?; let status = resp.status(); if status.as_u16() == 401 || status.as_u16() == 403 { return Err(ProbeFailure::auth("访问令牌无效或已被吊销")); } if !status.is_success() { return Err(ProbeFailure::server(format!("HTTP {}", status.as_u16()))); } let raw = resp .json::>() .await .map_err(|e| ProbeFailure::server(format!("状态响应解析失败:{e}")))?; Ok(raw.into_iter().map(to_summary).collect()) } fn attr_str(attrs: &serde_json::Value, key: &str) -> String { attrs .get(key) .and_then(|v| v.as_str()) .unwrap_or_default() .to_string() } fn attr_f64(attrs: &serde_json::Value, key: &str) -> Option { attrs.get(key).and_then(|v| v.as_f64()) } /// 0–255 的整数属性(亮度)。上界夹紧,避免异常集成给出超范围值反倒转换失败。 fn attr_u8(attrs: &serde_json::Value, key: &str) -> Option { attrs .get(key) .and_then(|v| v.as_u64()) .map(|n| n.min(255) as u8) } /// 0–100 的整数属性(窗帘位置 / 风扇档位)。 fn attr_pct(attrs: &serde_json::Value, key: &str) -> Option { attrs .get(key) .and_then(|v| v.as_u64()) .map(|n| n.min(100) as u8) } fn attr_u32(attrs: &serde_json::Value, key: &str) -> Option { attrs.get(key).and_then(|v| v.as_u64()).map(|n| n as u32) } /// 字符串数组属性(`supported_color_modes` / `hvac_modes`) fn attr_str_list(attrs: &serde_json::Value, key: &str) -> Vec { attrs .get(key) .and_then(|v| v.as_array()) .map(|a| { a.iter() .filter_map(|x| x.as_str().map(|s| s.to_string())) .collect() }) .unwrap_or_default() } /// HA 状态对象 → 精简结构。控制类命令(服务响应里带回的变化实体)也复用它, /// P4 的 WS 增量合并后同样走这里。 pub fn to_summary(raw: RawState) -> EntitySummary { let attrs = &raw.attributes; let domain = raw .entity_id .split('.') .next() .unwrap_or_default() .to_string(); let name = { let n = attr_str(attrs, "friendly_name"); if n.is_empty() { raw.entity_id.clone() } else { n } }; // sensor 的读数在 state 里(字符串形式的数字):能解析就顺手给前端一个数值 let numeric = raw.state.parse::().ok(); EntitySummary { entity_id: raw.entity_id, domain, name, state: raw.state, numeric, unit: attr_str(attrs, "unit_of_measurement"), device_class: attr_str(attrs, "device_class"), brightness: attr_u8(attrs, "brightness"), // 窗帘:HA 官方集成给 `current_position`,个别集成给 `position`,两个都认 position: attr_pct(attrs, "current_position").or_else(|| attr_pct(attrs, "position")), target_temp: attr_f64(attrs, "temperature"), min_temp: attr_f64(attrs, "min_temp"), max_temp: attr_f64(attrs, "max_temp"), current_temp: attr_f64(attrs, "current_temperature"), last_changed: raw.last_changed, last_triggered: attr_str(attrs, "last_triggered"), supported_features: attr_u32(attrs, "supported_features").unwrap_or(0), supported_color_modes: attr_str_list(attrs, "supported_color_modes"), min_color_temp_kelvin: attr_u32(attrs, "min_color_temp_kelvin"), max_color_temp_kelvin: attr_u32(attrs, "max_color_temp_kelvin"), color_temp_kelvin: attr_u32(attrs, "color_temp_kelvin"), hvac_modes: attr_str_list(attrs, "hvac_modes"), target_temp_step: attr_f64(attrs, "target_temp_step"), volume_level: attr_f64(attrs, "volume_level"), percentage: attr_pct(attrs, "percentage"), min: attr_f64(attrs, "min"), max: attr_f64(attrs, "max"), step: attr_f64(attrs, "step"), options: attr_str_list(attrs, "options"), } } // ============ 设备控制(P2) ============ /// 调用服务(控制设备)。 /// /// 返回 HA 在响应体里带回的**已变化实体**新状态(`200` 响应就是这些状态对象, /// 与 `/api/states` 同构)。解析失败时返回空列表而**不是报错**:命令本身已经成功, /// 状态只是"还没反映出来",不该因此告诉用户"控制失败"。 pub async fn call_service( base: &str, token: &str, insecure: bool, kind: EndpointKind, domain: &str, service: &str, entity_id: &str, params: &ServiceParams, ) -> Result, ProbeFailure> { let client = build_client(insecure, request_timeout(kind)).map_err(ProbeFailure::network)?; let mut body = serde_json::Map::new(); body.insert( "entity_id".to_string(), serde_json::Value::String(entity_id.to_string()), ); // 只带真正有值的参数:HA 各服务对 `null` 的处理并不统一 if let Some(v) = params.brightness_pct { body.insert("brightness_pct".into(), json!(v)); } if let Some(v) = params.color_temp_kelvin { body.insert("color_temp_kelvin".into(), json!(v)); } if let Some(v) = params.position { body.insert("position".into(), json!(v)); } if let Some(v) = params.temperature { body.insert("temperature".into(), json!(v)); } if let Some(v) = ¶ms.hvac_mode { body.insert("hvac_mode".into(), json!(v)); } if let Some(v) = params.percentage { body.insert("percentage".into(), json!(v)); } if let Some(v) = params.volume_level { body.insert("volume_level".into(), json!(v)); } if let Some(v) = params.value { body.insert("value".into(), json!(v)); } if let Some(v) = ¶ms.option { body.insert("option".into(), json!(v)); } let resp = client .post(format!("{base}/api/services/{domain}/{service}")) .bearer_auth(token) .json(&serde_json::Value::Object(body)) .send() .await .map_err(|e| ProbeFailure::network(describe_request_error(&e)))?; let status = resp.status(); if status.as_u16() == 401 || status.as_u16() == 403 { return Err(ProbeFailure::auth("访问令牌无效或已被吊销")); } if status.as_u16() == 404 { return Err(ProbeFailure::not_found("实体或服务不存在(设备可能已被移除)")); } if status.as_u16() == 400 { // HA 对参数不支持会返回可读的中文/英文 message,原样带给用户最有用 let text = resp.text().await.unwrap_or_default(); return Err(ProbeFailure::bad_request(extract_message(&text))); } if !status.is_success() { return Err(ProbeFailure::server(format!("HTTP {}", status.as_u16()))); } Ok(resp .json::>() .await .unwrap_or_default() .into_iter() .map(to_summary) .collect()) } /// 取单个实体状态(控制后的校正用)。 /// /// 只在校正窗口到期时才调用 —— 它不是常规路径,所以单独一个命令而不是重拉全量。 pub async fn fetch_entity( base: &str, token: &str, insecure: bool, kind: EndpointKind, entity_id: &str, ) -> Result { let client = build_client(insecure, request_timeout(kind)).map_err(ProbeFailure::network)?; let resp = client .get(format!("{base}/api/states/{entity_id}")) .bearer_auth(token) .send() .await .map_err(|e| ProbeFailure::network(describe_request_error(&e)))?; let status = resp.status(); if status.as_u16() == 401 || status.as_u16() == 403 { return Err(ProbeFailure::auth("访问令牌无效或已被吊销")); } if status.as_u16() == 404 { return Err(ProbeFailure::not_found("该实体已不存在")); } if !status.is_success() { return Err(ProbeFailure::server(format!("HTTP {}", status.as_u16()))); } let raw = resp .json::() .await .map_err(|e| ProbeFailure::server(format!("实体响应解析失败:{e}")))?; Ok(to_summary(raw)) } /// 从 HA 的错误响应里抠出可读的 `message`(响应不是 JSON 时退化为原文截断)。 fn extract_message(text: &str) -> String { let parsed = serde_json::from_str::(text) .ok() .and_then(|v| v.get("message").and_then(|m| m.as_str()).map(|s| s.to_string())); match parsed { Some(m) if !m.is_empty() => m, _ => { let short: String = text.chars().take(200).collect(); if short.is_empty() { "该服务不接受这些参数".to_string() } else { short } } } }