1use serde::{Deserialize, Serialize};
2
3open_string_enum! {
4 #[non_exhaustive]
6 TreeSource {
7 Cgroup => "cgroup",
8 Job => "job",
9 ProcessTree => "process_tree"
10 }
11}
12
13open_string_enum! {
14 #[non_exhaustive]
16 ResourceBound {
17 Lower => "lower"
18 }
19}
20
21#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
26#[non_exhaustive]
27pub struct ProcessGroup {
28 pub name: String,
29 pub count: u64,
30 pub cpu_ms: u64,
31 pub memory_bytes: u64,
32 #[serde(default, skip_serializing_if = "Option::is_none")]
34 pub bound: Option<ResourceBound>,
35}
36
37#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
48#[non_exhaustive]
49pub struct TreeOwn {
50 pub cpu_ms: u64,
51 pub memory_bytes: u64,
52 #[serde(default, skip_serializing_if = "Option::is_none")]
54 pub bound: Option<ResourceBound>,
55}
56
57#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
60#[non_exhaustive]
61pub struct TreeReading {
62 #[serde(default, skip_serializing_if = "Option::is_none")]
64 pub measured_at_ms: Option<u64>,
65 pub cpu_ms: u64,
66 pub memory_bytes: u64,
67 pub memory_kind: crate::ChildMemoryKind,
68 pub process_count: u64,
69 pub source: TreeSource,
70 #[serde(default, skip_serializing_if = "Option::is_none")]
72 pub bound: Option<ResourceBound>,
73 #[serde(default, skip_serializing_if = "Option::is_none")]
77 pub own: Option<TreeOwn>,
78 #[serde(default)]
82 pub groups: Vec<ProcessGroup>,
83}
84
85#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
88#[non_exhaustive]
89pub struct CpuLastHour {
90 pub cpu_ms: u64,
91 pub covered_ms: u64,
92 #[serde(default, skip_serializing_if = "Option::is_none")]
94 pub bound: Option<ResourceBound>,
95}
96
97#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
100#[non_exhaustive]
101pub struct DaemonResources {
102 #[serde(default, skip_serializing_if = "Option::is_none")]
104 pub measured_at_ms: Option<u64>,
105 pub pid: u32,
106 pub start_time_ms: u64,
107 pub version: String,
108 #[serde(default, skip_serializing_if = "Option::is_none")]
109 pub resources: Option<crate::ChildResourceUsage>,
110 #[serde(default, skip_serializing_if = "Option::is_none")]
111 pub cpu_last_hour: Option<CpuLastHour>,
112}
113
114#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
117#[non_exhaustive]
118pub struct AgentCommandResources {
119 #[serde(default, skip_serializing_if = "Option::is_none")]
121 pub measured_at_ms: Option<u64>,
122 pub module_id: String,
123 pub cpu_ms: u64,
124 pub memory_bytes: u64,
125 pub process_count: u64,
126 #[serde(default, skip_serializing_if = "Option::is_none")]
127 pub bound: Option<ResourceBound>,
128 #[serde(default, skip_serializing_if = "Option::is_none")]
131 pub unmeasured_finished: Option<u64>,
132 #[serde(default)]
134 pub groups: Vec<ProcessGroup>,
135 #[serde(default, skip_serializing_if = "Option::is_none")]
136 pub cpu_last_hour: Option<CpuLastHour>,
137}
138
139impl ProcessGroup {
140 #[must_use]
142 pub fn new(name: impl Into<String>, count: u64, cpu_ms: u64, memory_bytes: u64) -> Self {
143 Self {
144 name: name.into(),
145 count,
146 cpu_ms,
147 memory_bytes,
148 bound: None,
149 }
150 }
151
152 #[must_use]
154 pub fn with_bound(mut self, bound: Option<ResourceBound>) -> Self {
155 self.bound = bound;
156 self
157 }
158}
159
160impl TreeOwn {
161 #[must_use]
163 pub fn new(cpu_ms: u64, memory_bytes: u64) -> Self {
164 Self {
165 cpu_ms,
166 memory_bytes,
167 bound: None,
168 }
169 }
170
171 #[must_use]
173 pub fn with_bound(mut self, bound: Option<ResourceBound>) -> Self {
174 self.bound = bound;
175 self
176 }
177}
178
179impl TreeReading {
180 #[must_use]
182 pub fn with_measured_at_ms(mut self, measured_at_ms: Option<u64>) -> Self {
183 self.measured_at_ms = measured_at_ms;
184 self
185 }
186
187 #[must_use]
189 pub fn new(
190 cpu_ms: u64,
191 memory_bytes: u64,
192 memory_kind: crate::ChildMemoryKind,
193 process_count: u64,
194 source: TreeSource,
195 ) -> Self {
196 Self {
197 cpu_ms,
198 memory_bytes,
199 memory_kind,
200 process_count,
201 source,
202 measured_at_ms: None,
203 bound: None,
204 own: None,
205 groups: Vec::new(),
206 }
207 }
208
209 #[must_use]
211 pub fn with_bound(mut self, bound: Option<ResourceBound>) -> Self {
212 self.bound = bound;
213 self
214 }
215
216 #[must_use]
218 pub fn with_own(mut self, own: Option<TreeOwn>) -> Self {
219 self.own = own;
220 self
221 }
222
223 #[must_use]
225 pub fn with_groups(mut self, groups: Vec<ProcessGroup>) -> Self {
226 self.groups = groups;
227 self
228 }
229}
230
231impl CpuLastHour {
232 #[must_use]
234 pub fn new(cpu_ms: u64, covered_ms: u64) -> Self {
235 Self {
236 cpu_ms,
237 covered_ms,
238 bound: None,
239 }
240 }
241
242 #[must_use]
244 pub fn with_bound(mut self, bound: Option<ResourceBound>) -> Self {
245 self.bound = bound;
246 self
247 }
248}
249
250impl DaemonResources {
251 #[must_use]
253 pub fn with_measured_at_ms(mut self, measured_at_ms: Option<u64>) -> Self {
254 self.measured_at_ms = measured_at_ms;
255 self
256 }
257
258 #[must_use]
260 pub fn new(pid: u32, start_time_ms: u64, version: impl Into<String>) -> Self {
261 Self {
262 pid,
263 start_time_ms,
264 version: version.into(),
265 measured_at_ms: None,
266 resources: None,
267 cpu_last_hour: None,
268 }
269 }
270
271 #[must_use]
273 pub fn with_resources(mut self, resources: Option<crate::ChildResourceUsage>) -> Self {
274 self.resources = resources;
275 self
276 }
277
278 #[must_use]
280 pub fn with_cpu_last_hour(mut self, cpu_last_hour: Option<CpuLastHour>) -> Self {
281 self.cpu_last_hour = cpu_last_hour;
282 self
283 }
284}
285
286impl AgentCommandResources {
287 #[must_use]
289 pub fn with_measured_at_ms(mut self, measured_at_ms: Option<u64>) -> Self {
290 self.measured_at_ms = measured_at_ms;
291 self
292 }
293
294 #[must_use]
296 pub fn new(
297 module_id: impl Into<String>,
298 cpu_ms: u64,
299 memory_bytes: u64,
300 process_count: u64,
301 ) -> Self {
302 Self {
303 module_id: module_id.into(),
304 measured_at_ms: None,
305 cpu_ms,
306 memory_bytes,
307 process_count,
308 bound: None,
309 unmeasured_finished: None,
310 groups: Vec::new(),
311 cpu_last_hour: None,
312 }
313 }
314
315 #[must_use]
317 pub fn with_bound(mut self, bound: Option<ResourceBound>) -> Self {
318 self.bound = bound;
319 self
320 }
321
322 #[must_use]
324 pub fn with_unmeasured_finished(mut self, unmeasured_finished: Option<u64>) -> Self {
325 self.unmeasured_finished = unmeasured_finished;
326 self
327 }
328
329 #[must_use]
331 pub fn with_groups(mut self, groups: Vec<ProcessGroup>) -> Self {
332 self.groups = groups;
333 self
334 }
335
336 #[must_use]
338 pub fn with_cpu_last_hour(mut self, cpu_last_hour: Option<CpuLastHour>) -> Self {
339 self.cpu_last_hour = cpu_last_hour;
340 self
341 }
342}
343
344#[cfg(test)]
345mod tests {
346 use super::*;
347
348 #[test]
349 fn resource_measurement_times_round_trip_without_becoming_required() {
350 fn round_trip<T: serde::Serialize + serde::de::DeserializeOwned>(reading: T) {
351 let mut value = serde_json::to_value(reading).unwrap();
352 assert!(value.get("measured_at_ms").is_none());
353 value["measured_at_ms"] = serde_json::json!(1_800_000_000_123_u64);
354 let decoded: T = serde_json::from_value(value).unwrap();
355 assert_eq!(
356 serde_json::to_value(decoded).unwrap()["measured_at_ms"],
357 1_800_000_000_123_u64
358 );
359 }
360 round_trip(TreeReading::new(
361 10,
362 20,
363 crate::ChildMemoryKind::ResidentSet,
364 1,
365 TreeSource::ProcessTree,
366 ));
367 round_trip(DaemonResources::new(1, 2, "test"));
368 round_trip(AgentCommandResources::new("worker", 10, 20, 1));
369 }
370
371 #[test]
372 fn hour_bound_is_optional_and_independent_of_cumulative_bounds() {
373 let old: CpuLastHour =
374 serde_json::from_value(serde_json::json!({"cpu_ms":0,"covered_ms":60_000})).unwrap();
375 assert_eq!(old.bound, None);
376 assert!(serde_json::to_value(old).unwrap().get("bound").is_none());
377 let lower: CpuLastHour = serde_json::from_value(
378 serde_json::json!({"cpu_ms":0,"covered_ms":60_000,"bound":"lower","future":true}),
379 )
380 .unwrap();
381 assert_eq!(lower.bound, Some(ResourceBound::Lower));
382 assert_eq!(serde_json::to_value(lower).unwrap()["bound"], "lower");
383 }
384 use crate::{ClientControlResponse, SupervisorEntry, SupervisorHealthStatus};
385
386 #[test]
387 fn resource_totals_round_trip_and_ignore_unknown_members() {
388 #[derive(Deserialize, Serialize)]
391 struct OlderTreeReading {
392 cpu_ms: u64,
393 memory_bytes: u64,
394 memory_kind: crate::ChildMemoryKind,
395 process_count: u64,
396 source: TreeSource,
397 #[serde(default, skip_serializing_if = "Option::is_none")]
398 bound: Option<ResourceBound>,
399 #[serde(default)]
400 groups: Vec<ProcessGroup>,
401 }
402 let reading = TreeReading {
403 measured_at_ms: Some(1_800_000_000_123),
404 bound: None,
405 own: Some(TreeOwn {
406 cpu_ms: 23,
407 memory_bytes: 56,
408 bound: None,
409 }),
410 cpu_ms: 123,
411 memory_bytes: 456,
412 memory_kind: crate::ChildMemoryKind::ResidentSet,
413 process_count: 2,
414 source: TreeSource::ProcessTree,
415 groups: vec![ProcessGroup {
416 bound: None,
417 name: "compiler".into(),
418 count: 1,
419 cpu_ms: 100,
420 memory_bytes: 400,
421 }],
422 };
423 let mut module =
424 SupervisorEntry::new("module", "running", true, true, SupervisorHealthStatus::Ok)
425 .with_tree(Some(reading));
426 module.cpu_last_hour = Some(CpuLastHour {
427 cpu_ms: 120,
428 covered_ms: 60_000,
429 bound: Some(ResourceBound::Lower),
430 });
431 let response = ClientControlResponse::SupervisorList {
432 generation: 1,
433 modules: vec![module],
434 daemon: Some(DaemonResources {
435 measured_at_ms: Some(1_800_000_000_123),
436 pid: 1,
437 start_time_ms: 1_700_000_000_000,
438 version: "1.0.0".into(),
439 resources: None,
440 cpu_last_hour: Some(CpuLastHour {
441 cpu_ms: 5,
442 covered_ms: 60_000,
443 bound: None,
444 }),
445 }),
446 agent_commands: Some(vec![AgentCommandResources {
447 measured_at_ms: Some(1_800_000_000_123),
448 module_id: "module".into(),
449 bound: None,
450 unmeasured_finished: None,
451 cpu_ms: 300,
452 memory_bytes: 100,
453 process_count: 1,
454 groups: Vec::new(),
455 cpu_last_hour: None,
456 }]),
457 };
458 let mut value = serde_json::to_value(&response).unwrap();
459 assert!(value["modules"][0].get("subtree").is_none());
460 value["future"] = serde_json::json!({"anything":true});
461 value["modules"][0]["future"] = serde_json::json!(1);
462 value["modules"][0]["tree"]["future"] = serde_json::json!(2);
463 value["modules"][0]["tree"]["own"]["future"] = serde_json::json!(true);
464 value["modules"][0]["tree"]["groups"][0]["future"] = serde_json::json!(3);
465 value["daemon"]["future"] = serde_json::json!(4);
466 value["agent_commands"][0]["future"] = serde_json::json!(5);
467 let older: OlderTreeReading =
468 serde_json::from_value(value["modules"][0]["tree"].clone()).unwrap();
469 let older = serde_json::to_value(older).unwrap();
470 assert!(older.get("own").is_none());
471 assert!(older.get("measured_at_ms").is_none());
472 assert_eq!(older["cpu_ms"], 123);
473 assert_eq!(older["groups"][0]["cpu_ms"], 100);
474 let decoded: ClientControlResponse = serde_json::from_value(value).unwrap();
475 assert_eq!(decoded, response);
476 let ClientControlResponse::SupervisorList { modules, .. } = decoded else {
477 panic!("wrong response")
478 };
479 assert_eq!(modules[0].tree.as_ref().unwrap().cpu_ms, 123);
480 assert_eq!(
481 modules[0].cpu_last_hour.as_ref().unwrap().covered_ms,
482 60_000
483 );
484 }
485
486 #[test]
487 fn unknown_resource_totals_are_omitted_and_legacy_lists_decode() {
488 let value = serde_json::json!({"op":"supervisor.list","generation":1,"modules":[{
489 "module_id":"module","state":"stopped","enabled":false,"live":false,"health":"unknown"
490 }]});
491 let response: ClientControlResponse = serde_json::from_value(value).unwrap();
492 let encoded = serde_json::to_value(response).unwrap();
493 assert!(encoded.get("daemon").is_none());
494 assert!(encoded.get("agent_commands").is_none());
495 assert!(encoded["modules"][0].get("tree").is_none());
496 assert!(encoded["modules"][0].get("tree_unavailable").is_none());
497 assert!(encoded["modules"][0].get("cpu_last_hour").is_none());
498 }
499
500 #[test]
501 fn tree_unavailable_is_additive_and_preserves_unknown_reasons() {
502 #[derive(Deserialize)]
503 struct OlderEntry {
504 module_id: String,
505 #[serde(default)]
506 tree: Option<TreeReading>,
507 }
508
509 for reason in [
510 "not_yet_measured",
511 "not_running",
512 "unreadable",
513 "launch_changed",
514 "future_reason",
515 ] {
516 let entry = SupervisorEntry::new(
517 "module",
518 "running",
519 true,
520 true,
521 SupervisorHealthStatus::Unknown,
522 )
523 .with_tree_unavailable(Some(reason.to_owned()));
524 let bytes = serde_json::to_vec(&entry).unwrap();
525 assert_eq!(
526 String::from_utf8(bytes.clone()).unwrap(),
527 format!(
528 r#"{{"module_id":"module","state":"running","enabled":true,"live":true,"protocol":"subc","health":"unknown","last_probe_ms":null,"tree_unavailable":"{reason}"}}"#
529 )
530 );
531 assert_eq!(
532 serde_json::from_slice::<SupervisorEntry>(&bytes).unwrap(),
533 entry
534 );
535 let older: OlderEntry = serde_json::from_slice(&bytes).unwrap();
536 assert_eq!(older.module_id, "module");
537 assert!(older.tree.is_none());
538 }
539 }
540}
541
542#[cfg(test)]
543mod optional_member_tests {
544 use super::*;
545 use serde::de::DeserializeOwned;
546 use serde_json::{json, Value};
547
548 fn refuses_missing<T: DeserializeOwned>(base: &Value, fields: &[&str]) {
549 for field in fields {
550 let mut missing = base.clone();
551 missing.as_object_mut().unwrap().remove(*field);
552 assert!(
553 serde_json::from_value::<T>(missing).is_err(),
554 "missing {field} must not become zero"
555 );
556 }
557 }
558
559 #[test]
560 fn nested_resource_types_default_only_optional_members_and_collections() {
561 let tree = json!({"cpu_ms":1,"memory_bytes":2,"memory_kind":"resident_set","process_count":3,"source":"cgroup"});
562 let reading: TreeReading = serde_json::from_value(tree.clone()).unwrap();
563 assert!(reading.groups.is_empty());
564 assert!(reading.bound.is_none());
565 assert!(reading.own.is_none());
566 assert!(serde_json::to_value(&reading).unwrap().get("own").is_none());
567 refuses_missing::<TreeReading>(
568 &tree,
569 &[
570 "cpu_ms",
571 "memory_bytes",
572 "memory_kind",
573 "process_count",
574 "source",
575 ],
576 );
577
578 let agents = json!({"module_id":"compiler","cpu_ms":1,"memory_bytes":2,"process_count":3});
579 let reading: AgentCommandResources = serde_json::from_value(agents.clone()).unwrap();
580 assert!(reading.groups.is_empty());
581 assert!(reading.bound.is_none());
582 assert!(reading.unmeasured_finished.is_none());
583 assert!(reading.cpu_last_hour.is_none());
584 refuses_missing::<AgentCommandResources>(
585 &agents,
586 &["module_id", "cpu_ms", "memory_bytes", "process_count"],
587 );
588
589 let daemon = json!({"pid":1,"start_time_ms":2,"version":"3"});
590 let reading: DaemonResources = serde_json::from_value(daemon.clone()).unwrap();
591 assert!(reading.resources.is_none());
592 assert!(reading.cpu_last_hour.is_none());
593 refuses_missing::<DaemonResources>(&daemon, &["pid", "start_time_ms", "version"]);
594
595 let group = json!({"name":"compiler","count":1,"cpu_ms":2,"memory_bytes":3});
597 assert!(serde_json::from_value::<ProcessGroup>(group.clone())
598 .unwrap()
599 .bound
600 .is_none());
601 refuses_missing::<ProcessGroup>(&group, &["name", "count", "cpu_ms", "memory_bytes"]);
602 let own = json!({"cpu_ms":2,"memory_bytes":3,"future":true});
603 let reading: TreeOwn = serde_json::from_value(own.clone()).unwrap();
604 assert!(reading.bound.is_none());
605 assert_eq!(
606 serde_json::to_value(reading).unwrap(),
607 json!({"cpu_ms":2,"memory_bytes":3})
608 );
609 refuses_missing::<TreeOwn>(&own, &["cpu_ms", "memory_bytes"]);
610 }
611
612 #[test]
613 fn lower_bounds_and_unmeasured_finishes_round_trip_additively() {
614 let tree = json!({"cpu_ms":1,"memory_bytes":2,"memory_kind":"resident_set","process_count":3,"source":"process_tree","bound":"lower","own":{"cpu_ms":1,"memory_bytes":2,"bound":"lower","future":true},"future":true});
615 let reading: TreeReading = serde_json::from_value(tree.clone()).unwrap();
616 assert_eq!(reading.bound, Some(ResourceBound::Lower));
617 assert_eq!(
618 reading.own.as_ref().unwrap().bound,
619 Some(ResourceBound::Lower)
620 );
621 let encoded = serde_json::to_value(reading).unwrap();
622 assert_eq!(encoded["bound"], "lower");
623 assert_eq!(
624 encoded["own"],
625 json!({"cpu_ms":1,"memory_bytes":2,"bound":"lower"})
626 );
627 let group = json!({"name":"compiler","count":1,"cpu_ms":2,"memory_bytes":3,"bound":"lower","future":true});
628 let reading: ProcessGroup = serde_json::from_value(group).unwrap();
629 assert_eq!(reading.bound, Some(ResourceBound::Lower));
630 assert_eq!(serde_json::to_value(reading).unwrap()["bound"], "lower");
631 let agents = json!({"module_id":"compiler","cpu_ms":1,"memory_bytes":2,"process_count":0,"bound":"lower","unmeasured_finished":4,"future":true});
632 let reading: AgentCommandResources = serde_json::from_value(agents).unwrap();
633 assert_eq!(reading.unmeasured_finished, Some(4));
634 assert_eq!(serde_json::to_value(reading).unwrap()["bound"], "lower");
635 }
636}