Files
Thing/src-tauri/src/smarthome/client.rs
T
2026-10-23 17:25:17 +08:00

736 lines
26 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! 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<String>) -> Self {
Self {
kind: "auth",
message: message.into(),
fatal_auth: true,
}
}
fn network(message: impl Into<String>) -> Self {
Self {
kind: "network",
message: message.into(),
fatal_auth: false,
}
}
fn server(message: impl Into<String>) -> Self {
Self {
kind: "server",
message: message.into(),
fatal_auth: false,
}
}
/// 实体 / 服务不存在(设备被移除、集成重载)
fn not_found(message: impl Into<String>) -> Self {
Self {
kind: "notFound",
message: message.into(),
fatal_auth: false,
}
}
/// 参数不被该服务接受(如给不支持色温的灯传 `color_temp_kelvin`)
fn bad_request(message: impl Into<String>) -> 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<String>) -> 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<String, String> {
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, String> {
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<u64, ProbeFailure> {
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::<ApiRoot>().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<ProbeFailure> = 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<HaConfig, ProbeFailure> {
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::<HaConfig>()
.await
.map_err(|e| ProbeFailure::server(format!("响应解析失败:{e}")))
}
/// 逐个地址探测(顺序:局域网 → 反代),供「测试连接」使用。
pub async fn probe_all(
local_url: &str,
remote_url: &str,
token: &str,
insecure: bool,
) -> Vec<EndpointProbe> {
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<Vec<(&str, EndpointKind, u64)>, 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<ResolvedEndpoint, ResolveFailure> {
let list = candidates(conn)?;
let mut failures: Vec<String> = 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<Vec<EntitySummary>, 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::<Vec<RawState>>()
.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<f64> {
attrs.get(key).and_then(|v| v.as_f64())
}
/// 0–255 的整数属性(亮度)。上界夹紧,避免异常集成给出超范围值反倒转换失败。
fn attr_u8(attrs: &serde_json::Value, key: &str) -> Option<u8> {
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<u8> {
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<u32> {
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<String> {
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::<f64>().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<Vec<EntitySummary>, 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) = &params.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) = &params.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::<Vec<RawState>>()
.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<EntitySummary, ProbeFailure> {
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::<RawState>()
.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::<serde_json::Value>(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
}
}
}
}