code_system_graph_core/execution_policy/
tracker.rs1use std::sync::Arc;
2use std::time::{Duration, Instant};
3
4use super::{ExecutionLimitExceeded, ExecutionPolicy, ExecutionResource, JobPhase};
5
6pub trait MonotonicClock: std::fmt::Debug + Send + Sync {
8 fn now(&self) -> Duration;
10}
11
12#[derive(Debug)]
13struct SystemMonotonicClock {
14 origin: Instant,
15}
16
17impl SystemMonotonicClock {
18 fn new() -> Self {
19 Self {
20 origin: Instant::now(),
21 }
22 }
23}
24
25impl MonotonicClock for SystemMonotonicClock {
26 fn now(&self) -> Duration {
27 self.origin.elapsed()
28 }
29}
30
31#[derive(Debug)]
33pub struct ScanJobTracker {
34 run_id: String,
35 policy: ExecutionPolicy,
36 clock: Arc<dyn MonotonicClock>,
37 started: Duration,
38 last_progress: Duration,
39 phase: JobPhase,
40 completed_units: u64,
41}
42
43impl ScanJobTracker {
44 #[must_use]
46 pub fn new(run_id: impl Into<String>, policy: ExecutionPolicy) -> Self {
47 Self::with_clock(run_id, policy, Arc::new(SystemMonotonicClock::new()))
48 }
49
50 #[must_use]
52 pub fn with_clock(
53 run_id: impl Into<String>,
54 policy: ExecutionPolicy,
55 clock: Arc<dyn MonotonicClock>,
56 ) -> Self {
57 let now = clock.now();
58 Self {
59 run_id: run_id.into(),
60 policy,
61 clock,
62 started: now,
63 last_progress: now,
64 phase: JobPhase::Configuration,
65 completed_units: 0,
66 }
67 }
68
69 pub fn enter_phase(&mut self, phase: JobPhase) -> Result<(), ExecutionLimitExceeded> {
75 self.check_time()?;
76 self.phase = phase;
77 Ok(())
78 }
79
80 pub fn progress(&mut self, amount: u64) -> Result<(), ExecutionLimitExceeded> {
86 let completed_units = self
87 .completed_units
88 .checked_add(amount)
89 .ok_or_else(|| self.exceeded(ExecutionResource::WorkUnits, u64::MAX, u64::MAX - 1))?;
90 self.check_time()?;
91 self.completed_units = completed_units;
92 self.last_progress = self.clock.now();
93 Ok(())
94 }
95
96 pub fn check_time(&self) -> Result<(), ExecutionLimitExceeded> {
102 let now = self.clock.now();
103 self.check_duration(
104 ExecutionResource::WallTimeMs,
105 now.saturating_sub(self.started),
106 self.policy.max_scan_wall_time_ms,
107 )?;
108 self.check_duration(
109 ExecutionResource::NoProgressTimeMs,
110 now.saturating_sub(self.last_progress),
111 self.policy.max_no_progress_time_ms,
112 )
113 }
114
115 fn check_duration(
116 &self,
117 resource: ExecutionResource,
118 observed: Duration,
119 maximum: u64,
120 ) -> Result<(), ExecutionLimitExceeded> {
121 let observed = u64::try_from(observed.as_millis()).unwrap_or(u64::MAX);
122 if observed > maximum {
123 return Err(self.exceeded(resource, observed, maximum));
124 }
125 Ok(())
126 }
127
128 fn exceeded(
129 &self,
130 resource: ExecutionResource,
131 observed: u64,
132 maximum: u64,
133 ) -> ExecutionLimitExceeded {
134 ExecutionLimitExceeded {
135 run_id: self.run_id.clone(),
136 phase: self.phase,
137 resource,
138 observed,
139 maximum,
140 completed_units: self.completed_units,
141 }
142 }
143}
144
145#[cfg(test)]
146mod tests {
147 use std::sync::Arc;
148 use std::sync::atomic::{AtomicU64, Ordering};
149
150 use super::*;
151
152 #[derive(Debug, Default)]
153 struct FakeClock {
154 milliseconds: AtomicU64,
155 }
156
157 impl FakeClock {
158 fn advance(&self, milliseconds: u64) {
159 self.milliseconds.fetch_add(milliseconds, Ordering::Relaxed);
160 }
161 }
162
163 impl MonotonicClock for FakeClock {
164 fn now(&self) -> Duration {
165 Duration::from_millis(self.milliseconds.load(Ordering::Relaxed))
166 }
167 }
168
169 #[test]
170 fn injected_clock_should_accept_exact_deadline_and_reject_one_unit_over() {
171 let clock = Arc::new(FakeClock::default());
172 let policy = ExecutionPolicy {
173 max_scan_wall_time_ms: 10,
174 max_no_progress_time_ms: 10,
175 ..ExecutionPolicy::default()
176 };
177 let tracker = ScanJobTracker::with_clock("run", policy, clock.clone());
178
179 clock.advance(10);
180 tracker.check_time().expect("exact deadline is inclusive");
181 clock.advance(1);
182 let error = tracker.check_time().expect_err("one over must fail");
183
184 assert_eq!(error.resource, ExecutionResource::WallTimeMs);
185 assert_eq!(error.observed, 11);
186 assert_eq!(error.maximum, 10);
187 }
188
189 #[test]
190 fn phase_changes_should_not_fake_progress() {
191 let clock = Arc::new(FakeClock::default());
192 let policy = ExecutionPolicy {
193 max_scan_wall_time_ms: 100,
194 max_no_progress_time_ms: 5,
195 ..ExecutionPolicy::default()
196 };
197 let mut tracker = ScanJobTracker::with_clock("run", policy, clock.clone());
198
199 clock.advance(5);
200 tracker
201 .enter_phase(JobPhase::Discovery)
202 .expect("exact idle deadline is inclusive");
203 clock.advance(1);
204 let error = tracker
205 .enter_phase(JobPhase::Fingerprinting)
206 .expect_err("phase churn must not renew watchdog");
207
208 assert_eq!(error.resource, ExecutionResource::NoProgressTimeMs);
209 }
210}