Skip to main content

subc_control/
tree.rs

1use serde::{Deserialize, Serialize};
2
3open_string_enum! {
4    /// The measurement behind cumulative tree resources.
5    #[non_exhaustive]
6    TreeSource {
7        Cgroup => "cgroup",
8        Job => "job",
9        ProcessTree => "process_tree"
10    }
11}
12
13open_string_enum! {
14    /// Exact counters omit this member; uncontained or ambiguous CPU is a floor.
15    #[non_exhaustive]
16    ResourceBound {
17        Lower => "lower"
18    }
19}
20
21/// A live program group, ordered by descending memory in a tree reading.
22/// CPU is funded attributed credit of its currently live identities; the row
23/// additionally retains retired work. Groups never exceed their row's CPU.
24#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
25pub struct ProcessGroup {
26    pub name: String,
27    pub count: u64,
28    pub cpu_ms: u64,
29    pub memory_bytes: u64,
30    /// A live-only attributed CPU floor; absent means exact. Memory is not a floor.
31    #[serde(default, skip_serializing_if = "Option::is_none")]
32    pub bound: Option<ResourceBound>,
33}
34
35/// Cumulative CPU and current memory of a module and its descendants.
36#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
37pub struct TreeReading {
38    pub cpu_ms: u64,
39    pub memory_bytes: u64,
40    pub memory_kind: crate::ChildMemoryKind,
41    pub process_count: u64,
42    pub source: TreeSource,
43    /// Absent means exact. Memory and process count are not CPU bounds.
44    #[serde(default, skip_serializing_if = "Option::is_none")]
45    pub bound: Option<ResourceBound>,
46    /// Absent means no program groups. Unreadable members invalidate the whole
47    /// reading instead of being represented by an empty collection.
48    #[serde(default)]
49    pub groups: Vec<ProcessGroup>,
50}
51
52/// CPU used between the retained wall-clock samples, not a percentage.
53#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
54pub struct CpuLastHour {
55    pub cpu_ms: u64,
56    pub covered_ms: u64,
57    /// Only the covered hour is a floor; cumulative CPU has a separate bound.
58    #[serde(default, skip_serializing_if = "Option::is_none")]
59    pub bound: Option<ResourceBound>,
60}
61
62/// The daemon's own process, excluding CPU of its reaped module children.
63#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
64pub struct DaemonResources {
65    pub pid: u32,
66    pub start_time_ms: u64,
67    pub version: String,
68    #[serde(default, skip_serializing_if = "Option::is_none")]
69    pub resources: Option<crate::ChildResourceUsage>,
70    #[serde(default, skip_serializing_if = "Option::is_none")]
71    pub cpu_last_hour: Option<CpuLastHour>,
72}
73
74/// Commands attributed to agents rather than to the module that launches them.
75#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
76pub struct AgentCommandResources {
77    pub module_id: String,
78    pub cpu_ms: u64,
79    pub memory_bytes: u64,
80    pub process_count: u64,
81    #[serde(default, skip_serializing_if = "Option::is_none")]
82    pub bound: Option<ResourceBound>,
83    /// Accepted commands that finished before any successful CPU measurement.
84    /// Their CPU remains in the module row, not a fabricated agents zero.
85    #[serde(default, skip_serializing_if = "Option::is_none")]
86    pub unmeasured_finished: Option<u64>,
87    /// Absent means no live program groups, never unreadable members.
88    #[serde(default)]
89    pub groups: Vec<ProcessGroup>,
90    #[serde(default, skip_serializing_if = "Option::is_none")]
91    pub cpu_last_hour: Option<CpuLastHour>,
92}
93
94#[cfg(test)]
95mod tests {
96    use super::*;
97
98    #[test]
99    fn hour_bound_is_optional_and_independent_of_cumulative_bounds() {
100        let old: CpuLastHour =
101            serde_json::from_value(serde_json::json!({"cpu_ms":0,"covered_ms":60_000})).unwrap();
102        assert_eq!(old.bound, None);
103        assert!(serde_json::to_value(old).unwrap().get("bound").is_none());
104        let lower: CpuLastHour = serde_json::from_value(
105            serde_json::json!({"cpu_ms":0,"covered_ms":60_000,"bound":"lower","future":true}),
106        )
107        .unwrap();
108        assert_eq!(lower.bound, Some(ResourceBound::Lower));
109        assert_eq!(serde_json::to_value(lower).unwrap()["bound"], "lower");
110    }
111    use crate::{ClientControlResponse, SupervisorEntry, SupervisorHealthStatus};
112
113    #[test]
114    fn resource_totals_round_trip_and_ignore_unknown_members() {
115        let reading = TreeReading {
116            bound: None,
117            cpu_ms: 123,
118            memory_bytes: 456,
119            memory_kind: crate::ChildMemoryKind::ResidentSet,
120            process_count: 2,
121            source: TreeSource::ProcessTree,
122            groups: vec![ProcessGroup {
123                bound: None,
124                name: "compiler".into(),
125                count: 1,
126                cpu_ms: 100,
127                memory_bytes: 400,
128            }],
129        };
130        let mut module =
131            SupervisorEntry::new("module", "running", true, true, SupervisorHealthStatus::Ok)
132                .with_tree(Some(reading));
133        module.cpu_last_hour = Some(CpuLastHour {
134            cpu_ms: 120,
135            covered_ms: 60_000,
136            bound: Some(ResourceBound::Lower),
137        });
138        let response = ClientControlResponse::SupervisorList {
139            generation: 1,
140            modules: vec![module],
141            daemon: Some(DaemonResources {
142                pid: 1,
143                start_time_ms: 1_700_000_000_000,
144                version: "1.0.0".into(),
145                resources: None,
146                cpu_last_hour: Some(CpuLastHour {
147                    cpu_ms: 5,
148                    covered_ms: 60_000,
149                    bound: None,
150                }),
151            }),
152            agent_commands: Some(vec![AgentCommandResources {
153                module_id: "module".into(),
154                bound: None,
155                unmeasured_finished: None,
156                cpu_ms: 300,
157                memory_bytes: 100,
158                process_count: 1,
159                groups: Vec::new(),
160                cpu_last_hour: None,
161            }]),
162        };
163        let mut value = serde_json::to_value(&response).unwrap();
164        assert!(value["modules"][0].get("subtree").is_none());
165        value["future"] = serde_json::json!({"anything":true});
166        value["modules"][0]["future"] = serde_json::json!(1);
167        value["modules"][0]["tree"]["future"] = serde_json::json!(2);
168        value["modules"][0]["tree"]["groups"][0]["future"] = serde_json::json!(3);
169        value["daemon"]["future"] = serde_json::json!(4);
170        value["agent_commands"][0]["future"] = serde_json::json!(5);
171        let decoded: ClientControlResponse = serde_json::from_value(value).unwrap();
172        assert_eq!(decoded, response);
173        let ClientControlResponse::SupervisorList { modules, .. } = decoded else {
174            panic!("wrong response")
175        };
176        assert_eq!(modules[0].tree.as_ref().unwrap().cpu_ms, 123);
177        assert_eq!(
178            modules[0].cpu_last_hour.as_ref().unwrap().covered_ms,
179            60_000
180        );
181    }
182
183    #[test]
184    fn unknown_resource_totals_are_omitted_and_legacy_lists_decode() {
185        let value = serde_json::json!({"op":"supervisor.list","generation":1,"modules":[{
186            "module_id":"module","state":"stopped","enabled":false,"live":false,"health":"unknown"
187        }]});
188        let response: ClientControlResponse = serde_json::from_value(value).unwrap();
189        let encoded = serde_json::to_value(response).unwrap();
190        assert!(encoded.get("daemon").is_none());
191        assert!(encoded.get("agent_commands").is_none());
192        assert!(encoded["modules"][0].get("tree").is_none());
193        assert!(encoded["modules"][0].get("tree_unavailable").is_none());
194        assert!(encoded["modules"][0].get("cpu_last_hour").is_none());
195    }
196
197    #[test]
198    fn tree_unavailable_is_additive_and_preserves_unknown_reasons() {
199        #[derive(Deserialize)]
200        struct OlderEntry {
201            module_id: String,
202            #[serde(default)]
203            tree: Option<TreeReading>,
204        }
205
206        for reason in ["not_yet_measured", "future_reason"] {
207            let entry = SupervisorEntry::new(
208                "module",
209                "running",
210                true,
211                true,
212                SupervisorHealthStatus::Unknown,
213            )
214            .with_tree_unavailable(Some(reason.to_owned()));
215            let bytes = serde_json::to_vec(&entry).unwrap();
216            assert_eq!(
217                String::from_utf8(bytes.clone()).unwrap(),
218                format!(
219                    r#"{{"module_id":"module","state":"running","enabled":true,"live":true,"protocol":"subc","health":"unknown","last_probe_ms":null,"tree_unavailable":"{reason}"}}"#
220                )
221            );
222            assert_eq!(
223                serde_json::from_slice::<SupervisorEntry>(&bytes).unwrap(),
224                entry
225            );
226            let older: OlderEntry = serde_json::from_slice(&bytes).unwrap();
227            assert_eq!(older.module_id, "module");
228            assert!(older.tree.is_none());
229        }
230    }
231}
232
233#[cfg(test)]
234mod optional_member_tests {
235    use super::*;
236    use serde::de::DeserializeOwned;
237    use serde_json::{json, Value};
238
239    fn refuses_missing<T: DeserializeOwned>(base: &Value, fields: &[&str]) {
240        for field in fields {
241            let mut missing = base.clone();
242            missing.as_object_mut().unwrap().remove(*field);
243            assert!(
244                serde_json::from_value::<T>(missing).is_err(),
245                "missing {field} must not become zero"
246            );
247        }
248    }
249
250    #[test]
251    fn nested_resource_types_default_only_optional_members_and_collections() {
252        let tree = json!({"cpu_ms":1,"memory_bytes":2,"memory_kind":"resident_set","process_count":3,"source":"cgroup"});
253        let reading: TreeReading = serde_json::from_value(tree.clone()).unwrap();
254        assert!(reading.groups.is_empty());
255        assert!(reading.bound.is_none());
256        refuses_missing::<TreeReading>(
257            &tree,
258            &[
259                "cpu_ms",
260                "memory_bytes",
261                "memory_kind",
262                "process_count",
263                "source",
264            ],
265        );
266
267        let agents = json!({"module_id":"compiler","cpu_ms":1,"memory_bytes":2,"process_count":3});
268        let reading: AgentCommandResources = serde_json::from_value(agents.clone()).unwrap();
269        assert!(reading.groups.is_empty());
270        assert!(reading.bound.is_none());
271        assert!(reading.unmeasured_finished.is_none());
272        assert!(reading.cpu_last_hour.is_none());
273        refuses_missing::<AgentCommandResources>(
274            &agents,
275            &["module_id", "cpu_ms", "memory_bytes", "process_count"],
276        );
277
278        let daemon = json!({"pid":1,"start_time_ms":2,"version":"3"});
279        let reading: DaemonResources = serde_json::from_value(daemon.clone()).unwrap();
280        assert!(reading.resources.is_none());
281        assert!(reading.cpu_last_hour.is_none());
282        refuses_missing::<DaemonResources>(&daemon, &["pid", "start_time_ms", "version"]);
283
284        // Optional minimum metadata does not make any measurement optional.
285        let group = json!({"name":"compiler","count":1,"cpu_ms":2,"memory_bytes":3});
286        assert!(serde_json::from_value::<ProcessGroup>(group.clone())
287            .unwrap()
288            .bound
289            .is_none());
290        refuses_missing::<ProcessGroup>(&group, &["name", "count", "cpu_ms", "memory_bytes"]);
291    }
292
293    #[test]
294    fn lower_bounds_and_unmeasured_finishes_round_trip_additively() {
295        let tree = json!({"cpu_ms":1,"memory_bytes":2,"memory_kind":"resident_set","process_count":3,"source":"process_tree","bound":"lower","future":true});
296        let reading: TreeReading = serde_json::from_value(tree.clone()).unwrap();
297        assert_eq!(reading.bound, Some(ResourceBound::Lower));
298        assert_eq!(serde_json::to_value(reading).unwrap()["bound"], "lower");
299        let group = json!({"name":"compiler","count":1,"cpu_ms":2,"memory_bytes":3,"bound":"lower","future":true});
300        let reading: ProcessGroup = serde_json::from_value(group).unwrap();
301        assert_eq!(reading.bound, Some(ResourceBound::Lower));
302        assert_eq!(serde_json::to_value(reading).unwrap()["bound"], "lower");
303        let agents = json!({"module_id":"compiler","cpu_ms":1,"memory_bytes":2,"process_count":0,"bound":"lower","unmeasured_finished":4,"future":true});
304        let reading: AgentCommandResources = serde_json::from_value(agents).unwrap();
305        assert_eq!(reading.unmeasured_finished, Some(4));
306        assert_eq!(serde_json::to_value(reading).unwrap()["bound"], "lower");
307    }
308}