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 #[must_use]
71 pub const fn phase(&self) -> JobPhase {
72 self.phase
73 }
74
75 pub fn enter_phase(&mut self, phase: JobPhase) -> Result<(), ExecutionLimitExceeded> {
81 self.check_time()?;
82 self.phase = phase;
83 Ok(())
84 }
85
86 pub fn progress(&mut self, amount: u64) -> Result<(), ExecutionLimitExceeded> {
92 let completed_units = self
93 .completed_units
94 .checked_add(amount)
95 .ok_or_else(|| self.exceeded(ExecutionResource::WorkUnits, u64::MAX, u64::MAX - 1))?;
96 self.check_time()?;
97 self.completed_units = completed_units;
98 self.last_progress = self.clock.now();
99 Ok(())
100 }
101
102 pub fn check_time(&self) -> Result<(), ExecutionLimitExceeded> {
108 let now = self.clock.now();
109 self.check_duration(
110 ExecutionResource::WallTimeMs,
111 now.saturating_sub(self.started),
112 self.policy.max_scan_wall_time_ms,
113 )?;
114 self.check_duration(
115 ExecutionResource::NoProgressTimeMs,
116 now.saturating_sub(self.last_progress),
117 self.policy.max_no_progress_time_ms,
118 )
119 }
120
121 fn check_duration(
122 &self,
123 resource: ExecutionResource,
124 observed: Duration,
125 maximum: u64,
126 ) -> Result<(), ExecutionLimitExceeded> {
127 let observed = u64::try_from(observed.as_millis()).unwrap_or(u64::MAX);
128 if observed > maximum {
129 return Err(self.exceeded(resource, observed, maximum));
130 }
131 Ok(())
132 }
133
134 fn exceeded(
135 &self,
136 resource: ExecutionResource,
137 observed: u64,
138 maximum: u64,
139 ) -> ExecutionLimitExceeded {
140 ExecutionLimitExceeded {
141 run_id: self.run_id.clone(),
142 phase: self.phase,
143 resource,
144 observed,
145 maximum,
146 completed_units: self.completed_units,
147 }
148 }
149}
150
151#[cfg(test)]
152mod tests {
153 use std::sync::Arc;
154 use std::sync::atomic::{AtomicU64, Ordering};
155
156 use super::*;
157
158 #[derive(Debug, Default)]
159 struct FakeClock {
160 milliseconds: AtomicU64,
161 }
162
163 impl FakeClock {
164 fn advance(&self, milliseconds: u64) {
165 self.milliseconds.fetch_add(milliseconds, Ordering::Relaxed);
166 }
167 }
168
169 impl MonotonicClock for FakeClock {
170 fn now(&self) -> Duration {
171 Duration::from_millis(self.milliseconds.load(Ordering::Relaxed))
172 }
173 }
174
175 #[test]
176 fn injected_clock_should_accept_exact_deadline_and_reject_one_unit_over() {
177 let clock = Arc::new(FakeClock::default());
178 let policy = ExecutionPolicy {
179 max_scan_wall_time_ms: 10,
180 max_no_progress_time_ms: 10,
181 ..ExecutionPolicy::default()
182 };
183 let tracker = ScanJobTracker::with_clock("run", policy, clock.clone());
184
185 clock.advance(10);
186 tracker.check_time().expect("exact deadline is inclusive");
187 clock.advance(1);
188 let error = tracker.check_time().expect_err("one over must fail");
189
190 assert_eq!(error.resource, ExecutionResource::WallTimeMs);
191 assert_eq!(error.observed, 11);
192 assert_eq!(error.maximum, 10);
193 }
194
195 #[test]
196 fn phase_changes_should_not_fake_progress() {
197 let clock = Arc::new(FakeClock::default());
198 let policy = ExecutionPolicy {
199 max_scan_wall_time_ms: 100,
200 max_no_progress_time_ms: 5,
201 ..ExecutionPolicy::default()
202 };
203 let mut tracker = ScanJobTracker::with_clock("run", policy, clock.clone());
204
205 clock.advance(5);
206 tracker
207 .enter_phase(JobPhase::Discovery)
208 .expect("exact idle deadline is inclusive");
209 clock.advance(1);
210 let error = tracker
211 .enter_phase(JobPhase::Fingerprinting)
212 .expect_err("phase churn must not renew watchdog");
213
214 assert_eq!(error.resource, ExecutionResource::NoProgressTimeMs);
215 }
216}