Skip to main content

stateknot_runtime/agent_maintenance/
options.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4use super::AgentMaintenanceError;
5use std::time::Duration;
6
7/// Validated finite local pacing, dependency and shutdown bounds.
8#[derive(Clone, Debug)]
9pub struct AgentMaintenanceOptions {
10    pub(super) delay: Duration,
11    pub(super) failure_delay: Duration,
12    pub(super) tick_timeout: Duration,
13    pub(super) drain_timeout: Duration,
14    pub(super) probe_interval: Duration,
15    pub(super) probe_timeout: Duration,
16    pub(super) freshness: Duration,
17}
18impl Default for AgentMaintenanceOptions {
19    fn default() -> Self {
20        Self {
21            delay: Duration::from_millis(250),
22            failure_delay: Duration::from_secs(1),
23            tick_timeout: Duration::from_secs(30),
24            drain_timeout: Duration::from_secs(10),
25            probe_interval: Duration::from_secs(10),
26            probe_timeout: Duration::from_secs(5),
27            freshness: Duration::from_secs(20),
28        }
29    }
30}
31impl AgentMaintenanceOptions {
32    /// Positive 10 ms–60 s pacing after every ordinary or item-failing tick.
33    pub fn with_pacing(
34        mut self,
35        delay: Duration,
36        failure: Duration,
37    ) -> Result<Self, AgentMaintenanceError> {
38        if [delay, failure]
39            .iter()
40            .any(|value| !(Duration::from_millis(10)..=Duration::from_secs(60)).contains(value))
41        {
42            return Err(AgentMaintenanceError::InvalidOptions);
43        }
44        self.delay = delay;
45        self.failure_delay = failure;
46        Ok(self)
47    }
48    /// Absolute tick deadline 100 ms–1 h; graceful drain deadline 10 ms–5 min.
49    pub fn with_deadlines(
50        mut self,
51        tick: Duration,
52        drain: Duration,
53    ) -> Result<Self, AgentMaintenanceError> {
54        if !(Duration::from_millis(100)..=Duration::from_secs(3600)).contains(&tick)
55            || !(Duration::from_millis(10)..=Duration::from_secs(300)).contains(&drain)
56        {
57            return Err(AgentMaintenanceError::InvalidOptions);
58        }
59        self.tick_timeout = tick;
60        self.drain_timeout = drain;
61        Ok(self)
62    }
63    /// Single-flight probes: interval 50 ms–60 s, whole-check timeout 10 ms–30 s;
64    /// freshness at least their sum and at most 120 s.
65    pub fn with_readiness_limits(
66        mut self,
67        interval: Duration,
68        timeout: Duration,
69        freshness: Duration,
70    ) -> Result<Self, AgentMaintenanceError> {
71        if !(Duration::from_millis(50)..=Duration::from_secs(60)).contains(&interval)
72            || !(Duration::from_millis(10)..=Duration::from_secs(30)).contains(&timeout)
73            || freshness > Duration::from_secs(120)
74            || freshness < interval + timeout
75        {
76            return Err(AgentMaintenanceError::InvalidOptions);
77        }
78        self.probe_interval = interval;
79        self.probe_timeout = timeout;
80        self.freshness = freshness;
81        Ok(self)
82    }
83}
84
85#[cfg(test)]
86mod tests {
87    use super::*;
88    #[test]
89    fn bounds_reject_zero_overflow_and_inconsistent_freshness() {
90        let ms = Duration::from_millis;
91        for (a, b) in [(0, 10), (10, 0), (60001, 10), (10, 60001)] {
92            assert!(
93                AgentMaintenanceOptions::default()
94                    .with_pacing(ms(a), ms(b))
95                    .is_err()
96            );
97        }
98        for (a, b) in [(99, 10), (100, 9), (3_600_001, 10), (100, 300_001)] {
99            assert!(
100                AgentMaintenanceOptions::default()
101                    .with_deadlines(ms(a), ms(b))
102                    .is_err()
103            );
104        }
105        assert!(
106            AgentMaintenanceOptions::default()
107                .with_deadlines(ms(100), ms(10))
108                .is_ok()
109        );
110        assert!(
111            AgentMaintenanceOptions::default()
112                .with_readiness_limits(ms(50), ms(10), ms(59))
113                .is_err()
114        );
115        assert!(
116            AgentMaintenanceOptions::default()
117                .with_readiness_limits(ms(50), ms(10), ms(60))
118                .is_ok()
119        );
120        assert!(
121            AgentMaintenanceOptions::default()
122                .with_readiness_limits(Duration::MAX, ms(10), Duration::MAX)
123                .is_err()
124        );
125    }
126}