Skip to main content

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!(result.changed_pending.is_empty());
131        assert_eq!(result.expect, None);
132        assert_eq!(serde_json::to_string(&result).unwrap(), wire);
133    }
134
135    #[test]
136    fn pending_rescan_and_status_fields_round_trip_and_ignore_unknown_members() {
137        let wire = serde_json::json!({
138            "added":[], "removed":[], "changed_pending_reload":[], "unchanged":0,
139            "future_member": true,
140            "changed_pending":[{"module_id":"worker","fields":[{
141                "field":"register_timeout_s","applies":"next_supervision","future_member":42
142            }]}]
143        });
144        let result: SupervisorRescanResult = serde_json::from_value(wire).unwrap();
145        assert_eq!(
146            result.changed_pending[0].fields[0].applies,
147            crate::PendingModuleApply::NextSupervision
148        );
149        let status = serde_json::json!({
150            "module_id":"worker","state":"disabled","enabled":false,"live":false,"health":"unknown",
151            "pending":[{"field":"register_timeout_s","applies":"next_supervision","value":1800}]
152        });
153        let entry: crate::SupervisorEntry = serde_json::from_value(status).unwrap();
154        assert_eq!(entry.pending[0].value, Some(serde_json::json!(1800)));
155        let value = serde_json::to_value(entry).unwrap();
156        assert_eq!(value["pending"][0]["value"], 1800);
157        let later: crate::SupervisorPendingField = serde_json::from_value(serde_json::json!({
158            "field":"x","applies":"some_later_boundary"
159        }))
160        .unwrap();
161        assert_eq!(later.applies, crate::PendingModuleApply::Other);
162    }
163
164    /// The op has no default form: a body that leaves `preview` out says
165    /// neither which of the two forms it is, so it must not decode as one.
166    #[test]
167    fn a_checked_rescan_without_preview_does_not_decode() {
168        let wire = r#"{"op":"supervisor.rescan_checked","candidate":"{}"}"#;
169        assert!(serde_json::from_str::<ClientControlRequest>(wire).is_err());
170    }
171}