736 lines
26 KiB
Rust
736 lines
26 KiB
Rust
//! 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) = ¶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::<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
|
||
}
|
||
}
|
||
}
|
||
}
|