Skip to main content

wist_api/status/
v1.rs

1//! `agent/status` seam —— **v1** 基线。
2//!
3//! agentd 周期性上报自身状态(CPU/内存/工作状态/发现策略版本/证书状态/机器画像…),网关收下并落库。
4//! 冻结基线:只做**加性**兼容不动它;需要非加性变更就新开 `v2`。
5//! 约定见 `wist-design/doc/design/foundation/api-seam-inventory.md` §7。
6
7use serde::{Deserialize, Serialize};
8
9use wist_contracts::capability_report::LogsCapabilities;
10
11use super::{AgentLocalWork, AgentUplinkState, HostProfile};
12
13/// 本版本的线上版本号(与路由 `/api/v1/…` 一致)。
14pub const API_VERSION: &str = wist_contracts::API_VERSION_V1;
15
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
17#[serde(rename_all = "snake_case")]
18pub enum AgentWorkState {
19    Paused,
20    Resumed,
21}
22
23/// 工作状态变化(非告警、非失败):暂停/恢复各上报一次。
24#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
25#[serde(deny_unknown_fields)]
26pub struct AgentWorkStateChange {
27    pub input_id: String,
28    pub state: AgentWorkState,
29    pub reason: String,
30    pub at: String,
31}
32
33#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
34#[serde(deny_unknown_fields)]
35pub struct AgentStatusReport {
36    pub agent_id: String,
37    pub instance_id: String,
38    pub version: String,
39    /// Own resident-set size in bytes reported by the agent.
40    #[serde(default)]
41    pub memory_bytes: Option<u64>,
42    /// Agent 进程自身 CPU 占用,**单核口径**(100% = 占满一个核;多线程进程可 >100)。
43    ///
44    /// 它只统计 agent 进程**自己**的 CPU 时间(`getrusage(RUSAGE_SELF)`),不含它拉起的子进程。
45    #[serde(default)]
46    pub cpu_percent: Option<f64>,
47    /// Agent 所在机器的**逻辑核数**(`available_parallelism`)。
48    ///
49    /// 为什么必须和 `cpu_percent` 同一份上报带上来:`cpu_percent` 是单核口径,
50    /// 而运维看图时真正常问的是「这台机器被它占了百分之几」——那是 `cpu_percent / 核数`。
51    /// 少了核数,右侧那个数既算不出来、也无法复核(4 核上的 13% 和 64 核上的 13% 完全不是一回事)。
52    ///
53    /// 为什么让 agent 报原始值、而不是它自己算好整机占比:沿用本仓已有的取舍
54    /// (与 `discovery_policy_version`、事实摘要 digest 同理)——agent 只交**原始事实**
55    /// (自己的 CPU 时间、自己的核数),换算只留一处,在网关。agent 自算的派生值
56    /// 一旦算法退化,下游没有任何一层能发现。
57    #[serde(default)]
58    pub cpu_cores: Option<u32>,
59    /// Measured round-trip latency to the admin control plane in milliseconds.
60    #[serde(default)]
61    pub admin_latency_ms: Option<u64>,
62    /// 自上次上报以来的工作状态变化(paused/resumed),非告警、非失败。
63    #[serde(default)]
64    pub work_state_changes: Option<Vec<AgentWorkStateChange>>,
65    /// 本机**实际生效**的发现方向策略版本;`None` = 还没拿到策略表(在用内建默认周期)。
66    ///
67    /// 为什么必须由 agent 上报、而不是网关自己记账:网关知道自己**发布**了哪一版,
68    /// 但不知道某台机器**拉到并应用**了哪一版 —— 拉取可能失败、可能还没到轮询节拍、
69    /// 也可能拿到后被夹取。而运维要回答的正是那句「我改了策略,哪些机器还没生效」。
70    #[serde(default)]
71    pub discovery_policy_version: Option<i64>,
72    /// 本机**工作内容视图**(`state/work.json` 的子集):我手里有哪些工作、各自在采哪些文件、
73    /// 一次性工作做到哪一步。
74    ///
75    /// 为什么必须由 agent 上报:网关知道自己**授权**了什么,但「真的在采哪些文件」只有 agent
76    /// 知道(本机手工加的输入、暂停、某条来源今天接不接得了)。网关侧只存最近一份。
77    /// `None` = 这台 agent 还没报过(旧版本 agent 不发这个字段)。
78    #[serde(default)]
79    pub local_work: Option<AgentLocalWork>,
80    /// 本机**实际生效**的采集输出状态(见 [`AgentUplinkState`])。
81    ///
82    /// 为什么必须由 agent 上报:网关知道自己**下发**了「启用 + 目标」,但不知道 agent
83    /// **生效**成了什么 —— grant 可能还没拉到、可能被本机总闸拦住、可能目标连不上。
84    /// 运维要回答的正是那句「这台为什么不上送」。
85    ///
86    /// `None` = 这台 agent 还没报过(旧版本 agent 不发这个字段)—— 落库后保持上一次的值
87    /// (与 `local_work` 同口径)。
88    #[serde(default)]
89    pub uplink_state: Option<AgentUplinkState>,
90    /// 本机**客户端证书**状态(mTLS);还没有证书时 `None`。
91    ///
92    /// 为什么要 agent 上报:证书与到期时间只有本机知道(服务端在握手期就验完了,
93    /// 而**过期证书根本进不来**);而「哪些机器快到期 / 已过期需重装」正是运维要提前看到的
94    /// (见 `docs/design/agent-identity-mtls.md` §5.5)。
95    ///
96    /// `None` = 这台 agent 还没报过 / 没证书 —— 落库后保持上一次的值(与其他可选字段同口径)。
97    #[serde(default)]
98    pub certificate_status: Option<AgentCertificateStatus>,
99    /// 机器画像(机器名 / `node_id` / `machine_id` / 网卡地址)—— 注册表里「这是哪台机器」的展示来源。
100    ///
101    /// 为什么由状态上报带(而不是只靠注册):**凭证书首触重建**登记时,机器画像全是空的
102    /// (证书只承载稳定身份),原设计指望「后续状态上报补齐」,但那条通道以前没有这些字段 ——
103    /// 于是经证书注册的机器在管理面永远只剩一个 ID。这里把注册时的 `HostProfile` 原样带上。
104    ///
105    /// `None` = 老版本 agentd 没带 —— 落库后保持上一次的值(与 `local_work` / `uplink_state` 同口径)。
106    #[serde(default)]
107    pub machine_profile: Option<HostProfile>,
108    /// 本机**能承接的日志形态 / 导出器**(D7 能力协商)。
109    ///
110    /// 为什么要 agent 报、而不是网关按 `version` 推:版本号只能回答“新旧”,回答不了
111    /// “这一版在**这个环境**里真能不能采”(导出器依赖的二进制可能没装、单层 glob 支持是
112    /// 一个具体能力而不是一个版本)。而回滚场景里最容易出错的就是“新目录 + 回滚后的 agent” ——
113    /// 网关必须看**它自己说了什么**。
114    ///
115    /// `None` = 旧版本 agentd 没报:网关按“未知”处理 —— 依赖新能力(glob / 新导出器)的单元
116    /// **不算可采**,宁可少派也不派下去报 unsupported。
117    #[serde(default)]
118    pub logs_capabilities: Option<LogsCapabilities>,
119    /// 本机对网关下发的**一次性命令**的处理结果(见 [`AgentCommandAck`])。
120    ///
121    /// 空 = 本次没有要确认的命令,字段不出现。**加性字段**:本结构是
122    /// `deny_unknown_fields`,所以部署顺序必须 **gateway 先于 agentd**(与本文件其它
123    /// 新增字段同一条规则,见 `CHANGELOG` 的升级提示)。
124    #[serde(default, skip_serializing_if = "Vec::is_empty")]
125    pub command_acks: Vec<AgentCommandAck>,
126}
127
128/// agent 本地客户端证书状态(上报给网关,供页面/告警展示)。
129#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
130#[serde(deny_unknown_fields)]
131pub struct AgentCertificateStatus {
132    /// 证书到期时刻(RFC3339)。
133    pub not_after: String,
134    /// 距到期的剩余秒数(已过期为负)。
135    pub remaining_seconds: i64,
136    /// `valid` / `renew_due` / `expired`。
137    pub state: String,
138    /// agent 本机**最近一次续签判定**的结果(§5.5)。
139    ///
140    /// `None` = 老版本 agentd 不发(或本机台账一时读不到)—— 网关落库时**保留上一次的值**
141    /// (与本报告里 `local_work` / `uplink_state` 同一口径)。
142    #[serde(default)]
143    pub last_renewal: Option<AgentCredentialRenewal>,
144}
145
146/// agent 本机**最近一次续签判定**的结果(§5.5)。
147///
148/// 续签是后台动作,**不记录就等于静默**:agentd 把本地台账(`identity/renewal.json`)原样带上来,
149/// 网关只存 / 展示,不重算。与 [`AgentCertificateStatus`] 同口径:`None` = 还没报过。
150#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
151#[serde(deny_unknown_fields)]
152pub struct AgentCredentialRenewal {
153    /// `not_due` / `renewed` / `failed` / `needs_reinstall` / `revoked`(与 agentd 本地台账同口径)。
154    pub outcome: String,
155    /// 本次判定时刻(RFC3339)。
156    pub checked_at: String,
157    /// 人读细节(失败原因 / 续到了什么时候…);无内容时为空串。
158    pub detail: String,
159    /// 续签后证书的到期时刻(RFC3339);无证书时为空串。
160    pub not_after: String,
161}
162
163/// 状态上报的**回执**。
164#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
165#[serde(deny_unknown_fields)]
166pub struct AgentStatusAck {
167    pub agent_id: String,
168    pub instance_id: String,
169    pub acknowledged_at: String,
170    /// 网关下发的待执行命令;没有命令时字段不出现。
171    ///
172    /// 为什么放在回执里:agent 没有入站监听面,状态上报(3s)是唯一由网关**回话**的通道。
173    /// 这里放的是**通用命令信封**(`kind` + 可选参数),而不是每条命令一个字段 ——
174    /// 新增一种命令只加一个 kind 词表值,不再改报文形状。
175    #[serde(default, skip_serializing_if = "Vec::is_empty")]
176    pub commands: Vec<AgentCommand>,
177}
178
179/// 网关下发给 agent 的一次性命令。
180///
181/// 与「期望状态」(工作 / 上送 / 策略)刻意分开:那些是可重拉的幂等快照,
182/// 这里是**一次执行**的动作,有明确的 `command_id`、结果与去重语义。
183///
184/// `command_id` 是去重键:agent 把处理过的命令写进本地台账,网关在没有收到
185/// `command_acks` 时会重发同一条;agent 见到同一个 id 不重复跑,只补结果。
186#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
187#[serde(deny_unknown_fields)]
188pub struct AgentCommand {
189    pub command_id: String,
190    /// 网关受理时刻(墙钟毫秒):agent 用它判过期。
191    pub requested_at_ms: i64,
192    /// 命令词表(见 [`command_kind`])。**开放字符串**:未知值由 agent 回
193    /// `unsupported`,而不是让整份回执解析失败。
194    pub kind: String,
195    /// 命令参数(JSON 文本;空 = 无参数)。不同 `kind` 自己解析,未知字段不进入本层。
196    #[serde(default, skip_serializing_if = "String::is_empty")]
197    pub params: String,
198}
199
200/// agent 对一条命令的处理结果(随下一次状态上报回传)。
201#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
202#[serde(deny_unknown_fields)]
203pub struct AgentCommandAck {
204    pub command_id: String,
205    /// 见 [`command_outcome`]。
206    pub outcome: String,
207    /// 人读细节(失败原因 / 探针统计…);无内容时省略。
208    #[serde(default, skip_serializing_if = "String::is_empty")]
209    pub detail: String,
210}
211
212/// 命令词表(`AgentCommand.kind`)。新增命令只在这里加一个值 + 一个执行分支。
213pub mod command_kind {
214    /// 立刻重采一次并上报事实(见 agentd `refresh-facts`)。
215    pub const REFRESH_FACTS: &str = "refresh_facts";
216}
217
218/// 命令结果词表(`AgentCommandAck.outcome`)。
219pub mod command_outcome {
220    /// 执行完成,效果已生效(重采:事实已上报)。
221    pub const SUCCEEDED: &str = "succeeded";
222    /// 执行了,但没达到目标(重采:事实上报失败)。
223    pub const FAILED: &str = "failed";
224    /// 执行了,但本机没有可用的上送通道(重采:输出是 `file`)。
225    pub const NO_UPLINK: &str = "no_uplink";
226    /// 没执行:本地最小间隔未到。
227    pub const THROTTLED: &str = "throttled";
228    /// 没执行:命令过期(网关下发后很久才被拿到)。
229    pub const STALE: &str = "stale";
230    /// 不认识这种 `kind`(旧 agent 收到新命令)。
231    pub const UNSUPPORTED: &str = "unsupported";
232    /// **仅网关侧**:未执行的旧命令被同 kind 的新命令覆盖。agent 不会回这个值。
233    pub const SUPERSEDED: &str = "superseded";
234    /// **仅网关侧**:命令超过待执行窗口(旧 agent 不认、或长期离线),网关不再下发。
235    pub const EXPIRED: &str = "expired";
236}
237
238#[cfg(test)]
239mod tests {
240    use super::{
241        AgentCertificateStatus, AgentCommandAck, AgentStatusAck, AgentStatusReport, AgentWorkState,
242        AgentWorkStateChange, command_outcome,
243    };
244
245    #[test]
246    fn agent_work_state_uses_snake_case_on_the_wire() {
247        assert_eq!(
248            serde_json::to_string(&AgentWorkState::Paused).unwrap(),
249            "\"paused\""
250        );
251        assert_eq!(
252            serde_json::to_string(&AgentWorkState::Resumed).unwrap(),
253            "\"resumed\""
254        );
255        let change = AgentWorkStateChange {
256            input_id: "app".to_string(),
257            state: AgentWorkState::Paused,
258            reason: "spool_over_limit".to_string(),
259            at: "2026-09-27T00:00:00Z".to_string(),
260        };
261        let json = serde_json::to_string(&change).expect("encode");
262        let back: AgentWorkStateChange = serde_json::from_str(&json).expect("decode");
263        assert_eq!(back, change);
264
265        // 与同族的 AgentStatusReport 一致:拒绝未知字段,避免字段漂移静默通过。
266        let mutated = json.replacen('{', "{\"extra\":1,", 1);
267        assert!(serde_json::from_str::<AgentWorkStateChange>(&mutated).is_err());
268    }
269
270    #[test]
271    fn a_minimal_agent_status_report_decodes_and_extra_keys_fail() {
272        // 旧版 agent 只发三个必填字段;其余全是 #[serde(default)]。
273        let json = r#"{"agent_id":"a","instance_id":"i","version":"0.1.5"}"#;
274        let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
275        assert_eq!(report.memory_bytes, None);
276        assert_eq!(report.cpu_percent, None);
277        assert_eq!(report.work_state_changes, None);
278        assert_eq!(report.discovery_policy_version, None);
279        assert!(report.local_work.is_none());
280        assert!(report.uplink_state.is_none());
281        assert!(report.certificate_status.is_none());
282        // 机器画像同样是可选的:旧版 agent 不带 -> None(网关落库时保持上一次的值)。
283        assert!(report.machine_profile.is_none());
284        // 命令结果同样可选(旧 agent 不带 = 没有要确认的命令)。
285        assert!(report.command_acks.is_empty());
286
287        assert!(
288            serde_json::from_str::<AgentStatusReport>(
289                r#"{"agent_id":"a","instance_id":"i","version":"v","nope":1}"#
290            )
291            .is_err()
292        );
293    }
294
295    /// 机器画像随状态上报带上时能如实解码(机器名 / node_id / 网卡地址)。
296    #[test]
297    fn an_agent_status_report_carries_the_machine_profile() {
298        let json = r#"{
299            "agent_id":"a","instance_id":"i","version":"0.1.24",
300            "machine_profile":{
301                "node_id":"node-1","hostname":"host-1","os":"linux","arch":"x86_64",
302                "machine_id":"mid-1","cloud_instance_id":null,"k8s_node_uid":null,
303                "ip_addresses":["en0 192.168.1.5/24","10.8.0.2"]
304            }
305        }"#;
306        let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
307        let profile = report.machine_profile.expect("machine_profile present");
308        assert_eq!(profile.hostname, "host-1");
309        assert_eq!(profile.node_id, "node-1");
310        assert_eq!(profile.machine_id, "mid-1");
311        assert_eq!(
312            profile.ip_addresses,
313            vec!["en0 192.168.1.5/24".to_string(), "10.8.0.2".to_string()]
314        );
315    }
316
317    /// 证书状态里的「最近一次续签」是可选的,且拒绝未知字段:
318    /// 旧 agentd 少发它必须仍能解码(上线顺序不一,网关不能因此 400)。
319    #[test]
320    fn certificate_status_last_renewal_is_optional_and_round_trips() {
321        let legacy =
322            r#"{"not_after":"2026-11-04T00:00:00Z","remaining_seconds":100,"state":"valid"}"#;
323        let status: AgentCertificateStatus = serde_json::from_str(legacy).expect("decode");
324        assert!(status.last_renewal.is_none());
325
326        let json = r#"{"not_after":"2026-11-04T00:00:00Z","remaining_seconds":100,"state":"valid",
327            "last_renewal":{"outcome":"renewed","checked_at":"2026-10-08T00:00:00Z",
328            "detail":"credential renewed","not_after":"2026-11-04T00:00:00Z"}}"#;
329        let status: AgentCertificateStatus = serde_json::from_str(json).expect("decode");
330        assert_eq!(
331            status.last_renewal.as_ref().expect("renewal").outcome,
332            "renewed"
333        );
334
335        let encoded = serde_json::to_string(&status).expect("encode");
336        let back: AgentCertificateStatus = serde_json::from_str(&encoded).expect("decode");
337        assert_eq!(back, status);
338
339        // 字段漂移(`last_renewal` 里多出未知键)必须显形。
340        let drifted = r#"{"not_after":"x","remaining_seconds":0,"state":"valid",
341            "last_renewal":{"outcome":"renewed","checked_at":"t","detail":"","not_after":"",
342            "extra":1}}"#;
343        assert!(serde_json::from_str::<AgentCertificateStatus>(drifted).is_err());
344    }
345
346    /// D7:能力清单可选;旧 agentd 不带时必须是 `None`(网关据此按“未知”处理)。
347    #[test]
348    fn logs_capabilities_are_optional_and_round_trip() {
349        let legacy = r#"{"agent_id":"a","instance_id":"i","version":"0.8.0"}"#;
350        let report: AgentStatusReport = serde_json::from_str(legacy).expect("decode");
351        assert!(report.logs_capabilities.is_none());
352
353        let json = r#"{"agent_id":"a","instance_id":"i","version":"0.9.0",
354            "logs_capabilities":{
355                "file_inputs":["absolute-path","glob"],
356                "multiline_modes":["none","indented"],
357                "exporters":["journalctl-kernel"]
358            }}"#;
359        let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
360        let logs = report.logs_capabilities.expect("logs_capabilities");
361        assert_eq!(logs.exporters, vec!["journalctl-kernel".to_string()]);
362        assert!(logs.file_inputs.contains(&"glob".to_string()));
363
364        // 字段漂移仍要显形(与同族结构一致)。
365        let drifted = r#"{"agent_id":"a","instance_id":"i","version":"v",
366            "logs_capabilities":{"file_inputs":[],"nope":1}}"#;
367        assert!(serde_json::from_str::<AgentStatusReport>(drifted).is_err());
368    }
369
370    /// 回执里可以带一批通用命令;旧网关不带这个字段时仍然是合法回执。
371    #[test]
372    fn a_status_ack_carries_optional_commands() {
373        let legacy = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t"}"#;
374        let ack: AgentStatusAck = serde_json::from_str(legacy).expect("decode");
375        assert!(ack.commands.is_empty());
376
377        let json = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
378            "commands":[{"command_id":"c-1","requested_at_ms":1700000000000,
379            "kind":"refresh_facts"}]}"#;
380        let ack: AgentStatusAck = serde_json::from_str(json).expect("decode");
381        assert_eq!(ack.commands.len(), 1);
382        let command = &ack.commands[0];
383        assert_eq!(command.command_id, "c-1");
384        assert_eq!(command.requested_at_ms, 1_700_000_000_000);
385        assert_eq!(command.kind, "refresh_facts");
386        assert!(command.params.is_empty());
387
388        // 没有命令时字段不出现:旧 agent(若未来开始解析回执)不会被空数组干扰。
389        let encoded = serde_json::to_string(&AgentStatusAck {
390            agent_id: "a".to_string(),
391            instance_id: "i".to_string(),
392            acknowledged_at: "t".to_string(),
393            commands: Vec::new(),
394        })
395        .expect("encode");
396        assert!(!encoded.contains("commands"));
397
398        // 命令里的字段漂移要显形。
399        let drifted = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
400            "commands":[{"command_id":"c-1","requested_at_ms":1,
401            "kind":"refresh_facts","nope":1}]}"#;
402        assert!(serde_json::from_str::<AgentStatusAck>(drifted).is_err());
403    }
404
405    /// 未知 kind 是**合法字符串**(旧 agent 要靠它回 `unsupported`),不是解析错误。
406    #[test]
407    fn an_unknown_command_kind_still_decodes() {
408        let json = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
409            "commands":[{"command_id":"c-9","requested_at_ms":1,"kind":"future_command"}]}"#;
410        let ack: AgentStatusAck = serde_json::from_str(json).expect("decode");
411        assert_eq!(ack.commands[0].kind, "future_command");
412    }
413
414    /// 新 agent 报告里的命令结果可选;旧 agent 不带时字段不出现。
415    #[test]
416    fn an_agent_status_report_can_carry_command_results() {
417        let legacy = r#"{"agent_id":"a","instance_id":"i","version":"0.9.0"}"#;
418        let report: AgentStatusReport = serde_json::from_str(legacy).expect("decode");
419        assert!(report.command_acks.is_empty());
420
421        let json = r#"{"agent_id":"a","instance_id":"i","version":"0.9.11",
422            "command_acks":[{"command_id":"c-1","outcome":"succeeded",
423            "detail":"probes=6 failed=0"}]}"#;
424        let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
425        assert_eq!(
426            report.command_acks,
427            vec![AgentCommandAck {
428                command_id: "c-1".to_string(),
429                outcome: command_outcome::SUCCEEDED.to_string(),
430                detail: "probes=6 failed=0".to_string(),
431            }]
432        );
433    }
434}