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::{InvestigationCapabilities, 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    /// 本机**调查能力**(见 [`InvestigationCapabilities`]):能跑哪些调查面、是不是 root。
120    ///
121    /// 为什么要 agent 报、而不是网关按版本推:调查是**一次性只读操作**,网关必须在
122    /// **入队前**就知道这台机器认不认识这个面 —— 否则会把命令发下去换一个 `unsupported`,
123    /// 管理面上只会显示成「命令失败」,而真正原因是「这台机器不会 / 没权限」。
124    ///
125    /// `None` = 旧版本 agentd 没报:网关按「未知」处理 —— **只允许**它自己确认支持的面
126    /// (目前没有),宁可让菜单置灰,也不发一条注定失败的调查。
127    #[serde(default)]
128    pub investigation_capabilities: Option<InvestigationCapabilities>,
129    /// 本机对网关下发的**一次性命令**的处理结果(见 [`AgentCommandAck`])。
130    ///
131    /// 空 = 本次没有要确认的命令,字段不出现。**加性字段**:本结构是
132    /// `deny_unknown_fields`,所以部署顺序必须 **gateway 先于 agentd**(与本文件其它
133    /// 新增字段同一条规则,见 `CHANGELOG` 的升级提示)。
134    #[serde(default, skip_serializing_if = "Vec::is_empty")]
135    pub command_acks: Vec<AgentCommandAck>,
136}
137
138/// agent 本地客户端证书状态(上报给网关,供页面/告警展示)。
139#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
140#[serde(deny_unknown_fields)]
141pub struct AgentCertificateStatus {
142    /// 证书到期时刻(RFC3339)。
143    pub not_after: String,
144    /// 距到期的剩余秒数(已过期为负)。
145    pub remaining_seconds: i64,
146    /// `valid` / `renew_due` / `expired`。
147    pub state: String,
148    /// agent 本机**最近一次续签判定**的结果(§5.5)。
149    ///
150    /// `None` = 老版本 agentd 不发(或本机台账一时读不到)—— 网关落库时**保留上一次的值**
151    /// (与本报告里 `local_work` / `uplink_state` 同一口径)。
152    #[serde(default)]
153    pub last_renewal: Option<AgentCredentialRenewal>,
154}
155
156/// agent 本机**最近一次续签判定**的结果(§5.5)。
157///
158/// 续签是后台动作,**不记录就等于静默**:agentd 把本地台账(`identity/renewal.json`)原样带上来,
159/// 网关只存 / 展示,不重算。与 [`AgentCertificateStatus`] 同口径:`None` = 还没报过。
160#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
161#[serde(deny_unknown_fields)]
162pub struct AgentCredentialRenewal {
163    /// `not_due` / `renewed` / `failed` / `needs_reinstall` / `revoked`(与 agentd 本地台账同口径)。
164    pub outcome: String,
165    /// 本次判定时刻(RFC3339)。
166    pub checked_at: String,
167    /// 人读细节(失败原因 / 续到了什么时候…);无内容时为空串。
168    pub detail: String,
169    /// 续签后证书的到期时刻(RFC3339);无证书时为空串。
170    pub not_after: String,
171}
172
173/// 状态上报的**回执**。
174#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
175#[serde(deny_unknown_fields)]
176pub struct AgentStatusAck {
177    pub agent_id: String,
178    pub instance_id: String,
179    pub acknowledged_at: String,
180    /// 网关下发的待执行命令;没有命令时字段不出现。
181    ///
182    /// 为什么放在回执里:agent 没有入站监听面,状态上报(3s)是唯一由网关**回话**的通道。
183    /// 这里放的是**通用命令信封**(`kind` + 可选参数),而不是每条命令一个字段 ——
184    /// 新增一种命令只加一个 kind 词表值,不再改报文形状。
185    #[serde(default, skip_serializing_if = "Vec::is_empty")]
186    pub commands: Vec<AgentCommand>,
187}
188
189/// 网关下发给 agent 的一次性命令。
190///
191/// 与「期望状态」(工作 / 上送 / 策略)刻意分开:那些是可重拉的幂等快照,
192/// 这里是**一次执行**的动作,有明确的 `command_id`、结果与去重语义。
193///
194/// `command_id` 是去重键:agent 把处理过的命令写进本地台账,网关在没有收到
195/// `command_acks` 时会重发同一条;agent 见到同一个 id 不重复跑,只补结果。
196#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
197#[serde(deny_unknown_fields)]
198pub struct AgentCommand {
199    pub command_id: String,
200    /// 网关受理时刻(墙钟毫秒):agent 用它判过期。
201    pub requested_at_ms: i64,
202    /// 命令词表(见 [`command_kind`])。**开放字符串**:未知值由 agent 回
203    /// `unsupported`,而不是让整份回执解析失败。
204    pub kind: String,
205    /// 命令参数(JSON 文本;空 = 无参数)。不同 `kind` 自己解析,未知字段不进入本层。
206    #[serde(default, skip_serializing_if = "String::is_empty")]
207    pub params: String,
208}
209
210/// agent 对一条命令的处理结果(随下一次状态上报回传)。
211#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
212#[serde(deny_unknown_fields)]
213pub struct AgentCommandAck {
214    pub command_id: String,
215    /// 见 [`command_outcome`]。
216    pub outcome: String,
217    /// 人读细节(失败原因 / 探针统计…);无内容时省略。
218    #[serde(default, skip_serializing_if = "String::is_empty")]
219    pub detail: String,
220}
221
222/// 命令词表(`AgentCommand.kind`)。新增命令只在这里加一个值 + 一个执行分支。
223pub mod command_kind {
224    /// 立刻重采一次并上报事实(见 agentd `refresh-facts`)。
225    pub const REFRESH_FACTS: &str = "refresh_facts";
226    /// 一次性只读调查(见 agentd `investigate`):当场查一个问题并给证据表。
227    ///
228    /// `params` 是题目自己的 JSON(`topic` + 题目选项);不认识的值由 agent 回 `unsupported`。
229    /// 完整报告**不走这里**:ack 只回结论摘要,报告本体走数据面 ` IVSREP: ` 帧。
230    pub const INVESTIGATE: &str = "investigate";
231}
232
233/// 命令结果词表(`AgentCommandAck.outcome`)。
234pub mod command_outcome {
235    /// 执行完成,效果已生效(重采:事实已上报)。
236    pub const SUCCEEDED: &str = "succeeded";
237    /// 执行了,但没达到目标(重采:事实上报失败)。
238    pub const FAILED: &str = "failed";
239    /// 执行了,但本机没有可用的上送通道(重采:输出是 `file`)。
240    pub const NO_UPLINK: &str = "no_uplink";
241    /// 没执行:本地最小间隔未到。
242    pub const THROTTLED: &str = "throttled";
243    /// 没执行:命令过期(网关下发后很久才被拿到)。
244    pub const STALE: &str = "stale";
245    /// 不认识这种 `kind`(旧 agent 收到新命令)。
246    pub const UNSUPPORTED: &str = "unsupported";
247    /// **仅网关侧**:未执行的旧命令被同 kind 的新命令覆盖。agent 不会回这个值。
248    pub const SUPERSEDED: &str = "superseded";
249    /// **仅网关侧**:命令超过待执行窗口(旧 agent 不认、或长期离线),网关不再下发。
250    pub const EXPIRED: &str = "expired";
251}
252
253#[cfg(test)]
254mod tests {
255    use super::{
256        AgentCertificateStatus, AgentCommandAck, AgentStatusAck, AgentStatusReport, AgentWorkState,
257        AgentWorkStateChange, command_outcome,
258    };
259
260    #[test]
261    fn agent_work_state_uses_snake_case_on_the_wire() {
262        assert_eq!(
263            serde_json::to_string(&AgentWorkState::Paused).unwrap(),
264            "\"paused\""
265        );
266        assert_eq!(
267            serde_json::to_string(&AgentWorkState::Resumed).unwrap(),
268            "\"resumed\""
269        );
270        let change = AgentWorkStateChange {
271            input_id: "app".to_string(),
272            state: AgentWorkState::Paused,
273            reason: "spool_over_limit".to_string(),
274            at: "2026-09-27T00:00:00Z".to_string(),
275        };
276        let json = serde_json::to_string(&change).expect("encode");
277        let back: AgentWorkStateChange = serde_json::from_str(&json).expect("decode");
278        assert_eq!(back, change);
279
280        // 与同族的 AgentStatusReport 一致:拒绝未知字段,避免字段漂移静默通过。
281        let mutated = json.replacen('{', "{\"extra\":1,", 1);
282        assert!(serde_json::from_str::<AgentWorkStateChange>(&mutated).is_err());
283    }
284
285    #[test]
286    fn a_minimal_agent_status_report_decodes_and_extra_keys_fail() {
287        // 旧版 agent 只发三个必填字段;其余全是 #[serde(default)]。
288        let json = r#"{"agent_id":"a","instance_id":"i","version":"0.1.5"}"#;
289        let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
290        assert_eq!(report.memory_bytes, None);
291        assert_eq!(report.cpu_percent, None);
292        assert_eq!(report.work_state_changes, None);
293        assert_eq!(report.discovery_policy_version, None);
294        assert!(report.local_work.is_none());
295        assert!(report.uplink_state.is_none());
296        assert!(report.certificate_status.is_none());
297        // 机器画像同样是可选的:旧版 agent 不带 -> None(网关落库时保持上一次的值)。
298        assert!(report.machine_profile.is_none());
299        // 命令结果同样可选(旧 agent 不带 = 没有要确认的命令)。
300        assert!(report.command_acks.is_empty());
301
302        assert!(
303            serde_json::from_str::<AgentStatusReport>(
304                r#"{"agent_id":"a","instance_id":"i","version":"v","nope":1}"#
305            )
306            .is_err()
307        );
308    }
309
310    /// 机器画像随状态上报带上时能如实解码(机器名 / node_id / 网卡地址)。
311    #[test]
312    fn an_agent_status_report_carries_the_machine_profile() {
313        let json = r#"{
314            "agent_id":"a","instance_id":"i","version":"0.1.24",
315            "machine_profile":{
316                "node_id":"node-1","hostname":"host-1","os":"linux","arch":"x86_64",
317                "machine_id":"mid-1","cloud_instance_id":null,"k8s_node_uid":null,
318                "ip_addresses":["en0 192.168.1.5/24","10.8.0.2"]
319            }
320        }"#;
321        let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
322        let profile = report.machine_profile.expect("machine_profile present");
323        assert_eq!(profile.hostname, "host-1");
324        assert_eq!(profile.node_id, "node-1");
325        assert_eq!(profile.machine_id, "mid-1");
326        assert_eq!(
327            profile.ip_addresses,
328            vec!["en0 192.168.1.5/24".to_string(), "10.8.0.2".to_string()]
329        );
330    }
331
332    /// 证书状态里的「最近一次续签」是可选的,且拒绝未知字段:
333    /// 旧 agentd 少发它必须仍能解码(上线顺序不一,网关不能因此 400)。
334    #[test]
335    fn certificate_status_last_renewal_is_optional_and_round_trips() {
336        let legacy =
337            r#"{"not_after":"2026-11-04T00:00:00Z","remaining_seconds":100,"state":"valid"}"#;
338        let status: AgentCertificateStatus = serde_json::from_str(legacy).expect("decode");
339        assert!(status.last_renewal.is_none());
340
341        let json = r#"{"not_after":"2026-11-04T00:00:00Z","remaining_seconds":100,"state":"valid",
342            "last_renewal":{"outcome":"renewed","checked_at":"2026-10-08T00:00:00Z",
343            "detail":"credential renewed","not_after":"2026-11-04T00:00:00Z"}}"#;
344        let status: AgentCertificateStatus = serde_json::from_str(json).expect("decode");
345        assert_eq!(
346            status.last_renewal.as_ref().expect("renewal").outcome,
347            "renewed"
348        );
349
350        let encoded = serde_json::to_string(&status).expect("encode");
351        let back: AgentCertificateStatus = serde_json::from_str(&encoded).expect("decode");
352        assert_eq!(back, status);
353
354        // 字段漂移(`last_renewal` 里多出未知键)必须显形。
355        let drifted = r#"{"not_after":"x","remaining_seconds":0,"state":"valid",
356            "last_renewal":{"outcome":"renewed","checked_at":"t","detail":"","not_after":"",
357            "extra":1}}"#;
358        assert!(serde_json::from_str::<AgentCertificateStatus>(drifted).is_err());
359    }
360
361    /// D7:能力清单可选;旧 agentd 不带时必须是 `None`(网关据此按“未知”处理)。
362    #[test]
363    fn logs_capabilities_are_optional_and_round_trip() {
364        let legacy = r#"{"agent_id":"a","instance_id":"i","version":"0.8.0"}"#;
365        let report: AgentStatusReport = serde_json::from_str(legacy).expect("decode");
366        assert!(report.logs_capabilities.is_none());
367
368        let json = r#"{"agent_id":"a","instance_id":"i","version":"0.9.0",
369            "logs_capabilities":{
370                "file_inputs":["absolute-path","glob"],
371                "multiline_modes":["none","indented"],
372                "exporters":["journalctl-kernel"]
373            }}"#;
374        let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
375        let logs = report.logs_capabilities.expect("logs_capabilities");
376        assert_eq!(logs.exporters, vec!["journalctl-kernel".to_string()]);
377        assert!(logs.file_inputs.contains(&"glob".to_string()));
378
379        // 字段漂移仍要显形(与同族结构一致)。
380        let drifted = r#"{"agent_id":"a","instance_id":"i","version":"v",
381            "logs_capabilities":{"file_inputs":[],"nope":1}}"#;
382        assert!(serde_json::from_str::<AgentStatusReport>(drifted).is_err());
383    }
384
385    /// 回执里可以带一批通用命令;旧网关不带这个字段时仍然是合法回执。
386    #[test]
387    fn a_status_ack_carries_optional_commands() {
388        let legacy = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t"}"#;
389        let ack: AgentStatusAck = serde_json::from_str(legacy).expect("decode");
390        assert!(ack.commands.is_empty());
391
392        let json = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
393            "commands":[{"command_id":"c-1","requested_at_ms":1700000000000,
394            "kind":"refresh_facts"}]}"#;
395        let ack: AgentStatusAck = serde_json::from_str(json).expect("decode");
396        assert_eq!(ack.commands.len(), 1);
397        let command = &ack.commands[0];
398        assert_eq!(command.command_id, "c-1");
399        assert_eq!(command.requested_at_ms, 1_700_000_000_000);
400        assert_eq!(command.kind, "refresh_facts");
401        assert!(command.params.is_empty());
402
403        // 没有命令时字段不出现:旧 agent(若未来开始解析回执)不会被空数组干扰。
404        let encoded = serde_json::to_string(&AgentStatusAck {
405            agent_id: "a".to_string(),
406            instance_id: "i".to_string(),
407            acknowledged_at: "t".to_string(),
408            commands: Vec::new(),
409        })
410        .expect("encode");
411        assert!(!encoded.contains("commands"));
412
413        // 命令里的字段漂移要显形。
414        let drifted = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
415            "commands":[{"command_id":"c-1","requested_at_ms":1,
416            "kind":"refresh_facts","nope":1}]}"#;
417        assert!(serde_json::from_str::<AgentStatusAck>(drifted).is_err());
418    }
419
420    /// 未知 kind 是**合法字符串**(旧 agent 要靠它回 `unsupported`),不是解析错误。
421    #[test]
422    fn an_unknown_command_kind_still_decodes() {
423        let json = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
424            "commands":[{"command_id":"c-9","requested_at_ms":1,"kind":"future_command"}]}"#;
425        let ack: AgentStatusAck = serde_json::from_str(json).expect("decode");
426        assert_eq!(ack.commands[0].kind, "future_command");
427    }
428
429    /// 新 agent 报告里的命令结果可选;旧 agent 不带时字段不出现。
430    #[test]
431    fn an_agent_status_report_can_carry_command_results() {
432        let legacy = r#"{"agent_id":"a","instance_id":"i","version":"0.9.0"}"#;
433        let report: AgentStatusReport = serde_json::from_str(legacy).expect("decode");
434        assert!(report.command_acks.is_empty());
435
436        let json = r#"{"agent_id":"a","instance_id":"i","version":"0.9.11",
437            "command_acks":[{"command_id":"c-1","outcome":"succeeded",
438            "detail":"probes=6 failed=0"}]}"#;
439        let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
440        assert_eq!(
441            report.command_acks,
442            vec![AgentCommandAck {
443                command_id: "c-1".to_string(),
444                outcome: command_outcome::SUCCEEDED.to_string(),
445                detail: "probes=6 failed=0".to_string(),
446            }]
447        );
448    }
449}