subc_control/rescan_checked.rs
1//! Wire shapes for `supervisor.rescan_checked`: a rescan preview computed on
2//! configuration text the caller supplies, which nothing is written from, and
3//! an apply that runs only while the daemon still matches that preview.
4
5use serde::{Deserialize, Serialize};
6
7/// Advertised in `server.describe` by a daemon that serves
8/// `supervisor.rescan_checked`. A client sends that op only when this is
9/// listed: an older daemon refuses the unknown op, so a client that skipped
10/// the check would fail closed rather than preview the file on disk.
11pub const RESCAN_CANDIDATE_PREVIEW_CAPABILITY: &str = "rescan-candidate-preview/v1";
12
13/// The largest candidate text, in bytes, a preview accepts. A daemon config
14/// file is a few kilobytes; the cap bounds what one request can make the
15/// daemon parse.
16pub const RESCAN_CANDIDATE_MAX_BYTES: usize = 1024 * 1024;
17
18/// Refusal code for an apply whose `expect` no longer matches the daemon: the
19/// file it reads hashes differently, or the staged generation has moved since
20/// the preview (another rescan with module changes ran, even one that failed
21/// partway, or the daemon restarted). Nothing was applied.
22pub const CONFIG_CHANGED_SINCE_PREVIEW: &str = "config_changed_since_preview";
23
24/// Refusal code for a preview whose candidate is longer than
25/// [`RESCAN_CANDIDATE_MAX_BYTES`].
26pub const RESCAN_CANDIDATE_TOO_LARGE: &str = "candidate_too_large";
27
28/// What must still match for the daemon to accept an apply of this preview,
29/// so the apply does what the preview described.
30#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
31pub struct RescanExpect {
32 /// Lowercase hex SHA-256 of the candidate text the preview parsed. The
33 /// apply hashes the file the daemon reads and refuses on any difference,
34 /// so the bytes applied are exactly the bytes previewed.
35 pub config_sha256: String,
36 /// The daemon's staged configuration at preview time.
37 pub staged_generation: StagedGeneration,
38}
39
40/// Names one state of the daemon's staged configuration. The counter alone is
41/// not enough: it starts again at zero when the daemon restarts, and a
42/// restarted daemon may hold different staged specs under the same number.
43#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
44pub struct StagedGeneration {
45 /// The `daemon_incarnation` the daemon stamps on its activity ledger and
46 /// spawn events: one value per daemon process lifetime.
47 pub incarnation: String,
48 /// Moves each time an executed rescan sets out to change the supervised
49 /// modules' staged or applied configuration within that incarnation. It
50 /// moves before the first change, so it also moves when that rescan fails
51 /// partway.
52 pub counter: u64,
53}
54
55open_string_enum! {
56 /// What applying a candidate would do to one module.
57 RescanModuleActionKind {
58 /// The launch inputs change and the module is running or due to run,
59 /// so it needs a restart to use them. A rescan only stages the new
60 /// inputs; it does not restart the module itself.
61 Restart => "restart",
62 /// No restart is needed: a health policy edit takes effect at once,
63 /// and a module that stays disabled uses its changed launch inputs
64 /// when it next starts.
65 Reload => "reload",
66 /// The module is enabled or added enabled, so the rescan starts it.
67 Start => "start",
68 /// The module is disabled or removed while enabled, so the rescan
69 /// stops it.
70 Stop => "stop",
71 }
72}
73
74/// One module's entry in a candidate preview.
75#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
76pub struct RescanModuleAction {
77 pub module_id: String,
78 pub action: RescanModuleActionKind,
79 /// For `restart` and `reload`: which parts of the module's entry changed,
80 /// from `program`, `arguments`, `environment`, `protocol`, `reserved`,
81 /// `reserved_prefixes`, `overlap` and `health`. A newer daemon may send
82 /// other names, so readers must not treat this list as complete.
83 #[serde(default, skip_serializing_if = "Vec::is_empty")]
84 pub changed: Vec<String>,
85 /// For `restart` and `stop`: how long, in ms, the module's drain will wait
86 /// for in-flight work to finish before it is torn down.
87 #[serde(default, skip_serializing_if = "Option::is_none")]
88 pub drain_timeout_ms: Option<u64>,
89 /// For `restart` and `stop`: each busy gauge the module's registration
90 /// declares, in declaration order, with its value from the daemon's
91 /// cached health metrics. The drain waits for these gauges to read zero.
92 #[serde(default, skip_serializing_if = "Vec::is_empty")]
93 pub busy_gauges: Vec<BusyGaugeReading>,
94}
95
96/// A declared busy gauge's last reading from the daemon's health cache.
97#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
98pub struct BusyGaugeReading {
99 pub gauge: String,
100 /// The value the cached health metrics hold for the gauge, as the module
101 /// sent it. Absent when they hold none, which includes a module that never
102 /// reported the gauge and a metrics object the cache replaced because it
103 /// was too large.
104 #[serde(default, skip_serializing_if = "Option::is_none")]
105 pub value: Option<serde_json::Value>,
106}
107
108#[cfg(test)]
109mod tests {
110 use super::*;
111 use crate::{ClientControlRequest, SupervisorRescanResult};
112
113 #[test]
114 fn an_action_a_newer_daemon_sends_round_trips_as_unknown() {
115 let wire = r#"{"module_id":"m","action":"swap"}"#;
116 let action: RescanModuleAction = serde_json::from_str(wire).unwrap();
117 assert_eq!(
118 action.action,
119 RescanModuleActionKind::Unknown("swap".to_string())
120 );
121 assert_eq!(serde_json::to_string(&action).unwrap(), wire);
122 }
123
124 #[test]
125 fn a_plain_rescan_reply_decodes_without_the_preview_fields() {
126 let wire = r#"{"added":[],"removed":[],"changed_pending_reload":[],"unchanged":1}"#;
127 let result: SupervisorRescanResult = serde_json::from_str(wire).unwrap();
128 assert!(result.module_actions.is_empty());
129 assert!(result.earlier_pending.is_empty());
130 assert_eq!(result.expect, None);
131 assert_eq!(serde_json::to_string(&result).unwrap(), wire);
132 }
133
134 /// The op has no default form: a body that leaves `preview` out says
135 /// neither which of the two forms it is, so it must not decode as one.
136 #[test]
137 fn a_checked_rescan_without_preview_does_not_decode() {
138 let wire = r#"{"op":"supervisor.rescan_checked","candidate":"{}"}"#;
139 assert!(serde_json::from_str::<ClientControlRequest>(wire).is_err());
140 }
141}