1use serde::{Deserialize, Serialize};
8
9use wist_contracts::capability_report::{InvestigationCapabilities, LogsCapabilities};
10
11use super::{AgentLocalWork, AgentUplinkState, HostProfile};
12
13pub 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#[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 #[serde(default)]
41 pub memory_bytes: Option<u64>,
42 #[serde(default)]
46 pub cpu_percent: Option<f64>,
47 #[serde(default)]
58 pub cpu_cores: Option<u32>,
59 #[serde(default)]
61 pub admin_latency_ms: Option<u64>,
62 #[serde(default)]
64 pub work_state_changes: Option<Vec<AgentWorkStateChange>>,
65 #[serde(default)]
71 pub discovery_policy_version: Option<i64>,
72 #[serde(default)]
79 pub local_work: Option<AgentLocalWork>,
80 #[serde(default)]
89 pub uplink_state: Option<AgentUplinkState>,
90 #[serde(default)]
98 pub certificate_status: Option<AgentCertificateStatus>,
99 #[serde(default)]
107 pub machine_profile: Option<HostProfile>,
108 #[serde(default)]
118 pub logs_capabilities: Option<LogsCapabilities>,
119 #[serde(default)]
128 pub investigation_capabilities: Option<InvestigationCapabilities>,
129 #[serde(default, skip_serializing_if = "Vec::is_empty")]
135 pub command_acks: Vec<AgentCommandAck>,
136}
137
138#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
140#[serde(deny_unknown_fields)]
141pub struct AgentCertificateStatus {
142 pub not_after: String,
144 pub remaining_seconds: i64,
146 pub state: String,
148 #[serde(default)]
153 pub last_renewal: Option<AgentCredentialRenewal>,
154}
155
156#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
161#[serde(deny_unknown_fields)]
162pub struct AgentCredentialRenewal {
163 pub outcome: String,
165 pub checked_at: String,
167 pub detail: String,
169 pub not_after: String,
171}
172
173#[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 #[serde(default, skip_serializing_if = "Vec::is_empty")]
186 pub commands: Vec<AgentCommand>,
187}
188
189#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
197#[serde(deny_unknown_fields)]
198pub struct AgentCommand {
199 pub command_id: String,
200 pub requested_at_ms: i64,
202 pub kind: String,
205 #[serde(default, skip_serializing_if = "String::is_empty")]
207 pub params: String,
208}
209
210#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
212#[serde(deny_unknown_fields)]
213pub struct AgentCommandAck {
214 pub command_id: String,
215 pub outcome: String,
217 #[serde(default, skip_serializing_if = "String::is_empty")]
219 pub detail: String,
220}
221
222pub mod command_kind {
224 pub const REFRESH_FACTS: &str = "refresh_facts";
226 pub const INVESTIGATE: &str = "investigate";
231 pub const REFRESH: &str = "refresh";
235}
236
237pub mod refresh_what {
239 pub const FACTS: &str = "facts";
241 pub const POLICIES: &str = "policies";
243 pub const WORK: &str = "work";
245 pub const METRICS_LABELS: &str = "metrics-labels";
248 pub const CREDENTIALS: &str = "credentials";
250 pub const UPLINK: &str = "uplink";
252
253 pub const ALL: &[&str] = &[FACTS, POLICIES, WORK, METRICS_LABELS, CREDENTIALS, UPLINK];
257}
258
259#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
261#[serde(deny_unknown_fields)]
262pub struct RefreshParams {
263 pub what: Vec<String>,
265}
266
267pub mod command_outcome {
269 pub const SUCCEEDED: &str = "succeeded";
271 pub const FAILED: &str = "failed";
273 pub const NO_UPLINK: &str = "no_uplink";
275 pub const THROTTLED: &str = "throttled";
277 pub const STALE: &str = "stale";
279 pub const UNSUPPORTED: &str = "unsupported";
281 pub const ACCEPTED: &str = "accepted";
287 pub const SUPERSEDED: &str = "superseded";
289 pub const EXPIRED: &str = "expired";
291}
292
293#[cfg(test)]
294mod tests {
295 use super::{
296 AgentCertificateStatus, AgentCommandAck, AgentStatusAck, AgentStatusReport, AgentWorkState,
297 AgentWorkStateChange, command_outcome,
298 };
299
300 #[test]
301 fn agent_work_state_uses_snake_case_on_the_wire() {
302 assert_eq!(
303 serde_json::to_string(&AgentWorkState::Paused).unwrap(),
304 "\"paused\""
305 );
306 assert_eq!(
307 serde_json::to_string(&AgentWorkState::Resumed).unwrap(),
308 "\"resumed\""
309 );
310 let change = AgentWorkStateChange {
311 input_id: "app".to_string(),
312 state: AgentWorkState::Paused,
313 reason: "spool_over_limit".to_string(),
314 at: "2026-09-27T00:00:00Z".to_string(),
315 };
316 let json = serde_json::to_string(&change).expect("encode");
317 let back: AgentWorkStateChange = serde_json::from_str(&json).expect("decode");
318 assert_eq!(back, change);
319
320 let mutated = json.replacen('{', "{\"extra\":1,", 1);
322 assert!(serde_json::from_str::<AgentWorkStateChange>(&mutated).is_err());
323 }
324
325 #[test]
326 fn a_minimal_agent_status_report_decodes_and_extra_keys_fail() {
327 let json = r#"{"agent_id":"a","instance_id":"i","version":"0.1.5"}"#;
329 let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
330 assert_eq!(report.memory_bytes, None);
331 assert_eq!(report.cpu_percent, None);
332 assert_eq!(report.work_state_changes, None);
333 assert_eq!(report.discovery_policy_version, None);
334 assert!(report.local_work.is_none());
335 assert!(report.uplink_state.is_none());
336 assert!(report.certificate_status.is_none());
337 assert!(report.machine_profile.is_none());
339 assert!(report.command_acks.is_empty());
341
342 assert!(
343 serde_json::from_str::<AgentStatusReport>(
344 r#"{"agent_id":"a","instance_id":"i","version":"v","nope":1}"#
345 )
346 .is_err()
347 );
348 }
349
350 #[test]
352 fn an_agent_status_report_carries_the_machine_profile() {
353 let json = r#"{
354 "agent_id":"a","instance_id":"i","version":"0.1.24",
355 "machine_profile":{
356 "node_id":"node-1","hostname":"host-1","os":"linux","arch":"x86_64",
357 "machine_id":"mid-1","cloud_instance_id":null,"k8s_node_uid":null,
358 "ip_addresses":["en0 192.168.1.5/24","10.8.0.2"]
359 }
360 }"#;
361 let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
362 let profile = report.machine_profile.expect("machine_profile present");
363 assert_eq!(profile.hostname, "host-1");
364 assert_eq!(profile.node_id, "node-1");
365 assert_eq!(profile.machine_id, "mid-1");
366 assert_eq!(
367 profile.ip_addresses,
368 vec!["en0 192.168.1.5/24".to_string(), "10.8.0.2".to_string()]
369 );
370 }
371
372 #[test]
375 fn certificate_status_last_renewal_is_optional_and_round_trips() {
376 let legacy =
377 r#"{"not_after":"2026-11-04T00:00:00Z","remaining_seconds":100,"state":"valid"}"#;
378 let status: AgentCertificateStatus = serde_json::from_str(legacy).expect("decode");
379 assert!(status.last_renewal.is_none());
380
381 let json = r#"{"not_after":"2026-11-04T00:00:00Z","remaining_seconds":100,"state":"valid",
382 "last_renewal":{"outcome":"renewed","checked_at":"2026-10-08T00:00:00Z",
383 "detail":"credential renewed","not_after":"2026-11-04T00:00:00Z"}}"#;
384 let status: AgentCertificateStatus = serde_json::from_str(json).expect("decode");
385 assert_eq!(
386 status.last_renewal.as_ref().expect("renewal").outcome,
387 "renewed"
388 );
389
390 let encoded = serde_json::to_string(&status).expect("encode");
391 let back: AgentCertificateStatus = serde_json::from_str(&encoded).expect("decode");
392 assert_eq!(back, status);
393
394 let drifted = r#"{"not_after":"x","remaining_seconds":0,"state":"valid",
396 "last_renewal":{"outcome":"renewed","checked_at":"t","detail":"","not_after":"",
397 "extra":1}}"#;
398 assert!(serde_json::from_str::<AgentCertificateStatus>(drifted).is_err());
399 }
400
401 #[test]
403 fn logs_capabilities_are_optional_and_round_trip() {
404 let legacy = r#"{"agent_id":"a","instance_id":"i","version":"0.8.0"}"#;
405 let report: AgentStatusReport = serde_json::from_str(legacy).expect("decode");
406 assert!(report.logs_capabilities.is_none());
407
408 let json = r#"{"agent_id":"a","instance_id":"i","version":"0.9.0",
409 "logs_capabilities":{
410 "file_inputs":["absolute-path","glob"],
411 "multiline_modes":["none","indented"],
412 "exporters":["journalctl-kernel"]
413 }}"#;
414 let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
415 let logs = report.logs_capabilities.expect("logs_capabilities");
416 assert_eq!(logs.exporters, vec!["journalctl-kernel".to_string()]);
417 assert!(logs.file_inputs.contains(&"glob".to_string()));
418
419 let drifted = r#"{"agent_id":"a","instance_id":"i","version":"v",
421 "logs_capabilities":{"file_inputs":[],"nope":1}}"#;
422 assert!(serde_json::from_str::<AgentStatusReport>(drifted).is_err());
423 }
424
425 #[test]
427 fn a_status_ack_carries_optional_commands() {
428 let legacy = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t"}"#;
429 let ack: AgentStatusAck = serde_json::from_str(legacy).expect("decode");
430 assert!(ack.commands.is_empty());
431
432 let json = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
433 "commands":[{"command_id":"c-1","requested_at_ms":1700000000000,
434 "kind":"refresh_facts"}]}"#;
435 let ack: AgentStatusAck = serde_json::from_str(json).expect("decode");
436 assert_eq!(ack.commands.len(), 1);
437 let command = &ack.commands[0];
438 assert_eq!(command.command_id, "c-1");
439 assert_eq!(command.requested_at_ms, 1_700_000_000_000);
440 assert_eq!(command.kind, "refresh_facts");
441 assert!(command.params.is_empty());
442
443 let encoded = serde_json::to_string(&AgentStatusAck {
445 agent_id: "a".to_string(),
446 instance_id: "i".to_string(),
447 acknowledged_at: "t".to_string(),
448 commands: Vec::new(),
449 })
450 .expect("encode");
451 assert!(!encoded.contains("commands"));
452
453 let drifted = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
455 "commands":[{"command_id":"c-1","requested_at_ms":1,
456 "kind":"refresh_facts","nope":1}]}"#;
457 assert!(serde_json::from_str::<AgentStatusAck>(drifted).is_err());
458 }
459
460 #[test]
462 fn an_unknown_command_kind_still_decodes() {
463 let json = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
464 "commands":[{"command_id":"c-9","requested_at_ms":1,"kind":"future_command"}]}"#;
465 let ack: AgentStatusAck = serde_json::from_str(json).expect("decode");
466 assert_eq!(ack.commands[0].kind, "future_command");
467 }
468
469 #[test]
470 fn refresh_params_round_trip() {
471 let params = super::RefreshParams {
472 what: vec![
473 super::refresh_what::WORK.to_string(),
474 super::refresh_what::METRICS_LABELS.to_string(),
475 ],
476 };
477 let text = serde_json::to_string(¶ms).expect("serialize");
478 assert_eq!(text, r#"{"what":["work","metrics-labels"]}"#);
479 let parsed: super::RefreshParams = serde_json::from_str(&text).expect("deserialize");
480 assert_eq!(parsed, params);
481 }
482
483 #[test]
485 fn an_agent_status_report_can_carry_command_results() {
486 let legacy = r#"{"agent_id":"a","instance_id":"i","version":"0.9.0"}"#;
487 let report: AgentStatusReport = serde_json::from_str(legacy).expect("decode");
488 assert!(report.command_acks.is_empty());
489
490 let json = r#"{"agent_id":"a","instance_id":"i","version":"0.9.11",
491 "command_acks":[{"command_id":"c-1","outcome":"succeeded",
492 "detail":"probes=6 failed=0"}]}"#;
493 let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
494 assert_eq!(
495 report.command_acks,
496 vec![AgentCommandAck {
497 command_id: "c-1".to_string(),
498 outcome: command_outcome::SUCCEEDED.to_string(),
499 detail: "probes=6 failed=0".to_string(),
500 }]
501 );
502 }
503
504 #[test]
509 fn an_accepted_command_ack_keeps_its_wire_name() {
510 assert_eq!(command_outcome::ACCEPTED, "accepted");
511
512 let ack = AgentCommandAck {
513 command_id: "c-1".to_string(),
514 outcome: command_outcome::ACCEPTED.to_string(),
515 detail: "已取走,扫描中(最长 120s)".to_string(),
516 };
517 let json = serde_json::to_string(&ack).expect("encode");
518 assert!(
519 json.contains(r#""outcome":"accepted""#),
520 "阶段回报的 wire 值变了:{json}"
521 );
522 assert_eq!(
523 serde_json::from_str::<AgentCommandAck>(&json).expect("decode"),
524 ack
525 );
526
527 for terminal in [
529 command_outcome::SUCCEEDED,
530 command_outcome::FAILED,
531 command_outcome::NO_UPLINK,
532 command_outcome::THROTTLED,
533 command_outcome::STALE,
534 command_outcome::UNSUPPORTED,
535 ] {
536 assert_ne!(command_outcome::ACCEPTED, terminal);
537 }
538 }
539}