1use serde::{Deserialize, Serialize};
8
9use wist_contracts::capability_report::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, skip_serializing_if = "Vec::is_empty")]
125 pub command_acks: Vec<AgentCommandAck>,
126}
127
128#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
130#[serde(deny_unknown_fields)]
131pub struct AgentCertificateStatus {
132 pub not_after: String,
134 pub remaining_seconds: i64,
136 pub state: String,
138 #[serde(default)]
143 pub last_renewal: Option<AgentCredentialRenewal>,
144}
145
146#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
151#[serde(deny_unknown_fields)]
152pub struct AgentCredentialRenewal {
153 pub outcome: String,
155 pub checked_at: String,
157 pub detail: String,
159 pub not_after: String,
161}
162
163#[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 #[serde(default, skip_serializing_if = "Vec::is_empty")]
176 pub commands: Vec<AgentCommand>,
177}
178
179#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
187#[serde(deny_unknown_fields)]
188pub struct AgentCommand {
189 pub command_id: String,
190 pub requested_at_ms: i64,
192 pub kind: String,
195 #[serde(default, skip_serializing_if = "String::is_empty")]
197 pub params: String,
198}
199
200#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
202#[serde(deny_unknown_fields)]
203pub struct AgentCommandAck {
204 pub command_id: String,
205 pub outcome: String,
207 #[serde(default, skip_serializing_if = "String::is_empty")]
209 pub detail: String,
210}
211
212pub mod command_kind {
214 pub const REFRESH_FACTS: &str = "refresh_facts";
216}
217
218pub mod command_outcome {
220 pub const SUCCEEDED: &str = "succeeded";
222 pub const FAILED: &str = "failed";
224 pub const NO_UPLINK: &str = "no_uplink";
226 pub const THROTTLED: &str = "throttled";
228 pub const STALE: &str = "stale";
230 pub const UNSUPPORTED: &str = "unsupported";
232 pub const SUPERSEDED: &str = "superseded";
234 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 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 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 assert!(report.machine_profile.is_none());
284 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 #[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 #[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 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 #[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 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 #[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 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 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 #[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 #[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}