1pub(crate) mod baseline;
3mod process;
4use crate::graph::query_snapshot::QuerySnapshot;
5use crate::{
6 ContentId, Engine, EngineError, PlanId, PlanReceipt, RelPath, SnapshotId, SourceVersion,
7};
8use serde::{Deserialize, Serialize};
9use std::{
10 collections::BTreeMap,
11 time::{Duration, Instant},
12};
13
14#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
15#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
16#[serde(deny_unknown_fields)]
17pub struct CheckCommand {
18 pub name: String,
20 pub program: String,
22 #[serde(default)]
23 pub args: Vec<String>,
24}
25#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
26#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
27#[serde(default, deny_unknown_fields)]
28pub struct ValidationBudget {
29 #[cfg_attr(feature = "schema", schemars(range(min = 1, max = 300000)))]
32 pub timeout_ms: u64,
33 #[cfg_attr(feature = "schema", schemars(range(min = 4096, max = 1048576)))]
34 pub max_bytes: usize,
35}
36impl Default for ValidationBudget {
37 fn default() -> Self {
38 Self {
39 timeout_ms: 60_000,
40 max_bytes: 16_384,
41 }
42 }
43}
44impl ValidationBudget {
45 fn validate(&self) -> Result<(), EngineError> {
46 if !(1..=300_000).contains(&self.timeout_ms)
47 || !(4096..=1_048_576).contains(&self.max_bytes)
48 {
49 return Err(EngineError::InvalidBudget);
50 }
51 Ok(())
52 }
53}
54#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
55#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
56#[serde(deny_unknown_fields)]
57pub struct ValidatePlanQuery {
58 pub plan_id: PlanId,
59 #[cfg_attr(feature = "schema", schemars(length(min = 1, max = 4)))]
60 pub checks: Vec<CheckCommand>,
61 #[serde(default)]
63 #[cfg_attr(feature = "schema", schemars(length(max = 32)))]
64 pub extra_inputs: Vec<RelPath>,
65 #[serde(default)]
66 pub budget: ValidationBudget,
67}
68#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
69#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
70pub struct ValidationReport {
71 pub plan_id: PlanId,
72 pub history_id: u64,
73 pub run: u64,
75 pub sources: Vec<SourceVersion>,
76 pub before: SnapshotId,
77 pub after: Option<SnapshotId>,
78 pub input_files: usize,
79 pub extra_inputs: Vec<RelPath>,
80 pub source_state: ValidationSourceState,
81 pub passed: bool,
83 pub checks: Vec<CheckResult>,
84}
85#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
86#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
87#[serde(rename_all = "snake_case")]
88pub enum ValidationSourceState {
89 Unchanged,
90 Changed,
91 Unavailable,
92}
93#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
94#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
95#[serde(rename_all = "snake_case")]
96pub enum CheckOutcome {
97 NotRun,
98 Passed,
99 Failed,
100 TimedOut,
101 Cancelled,
102 Error,
103}
104#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
105#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
106pub struct CheckResult {
107 pub command: CheckCommand,
108 pub outcome: CheckOutcome,
109 pub exit_code: Option<i32>,
110 pub duration_ms: u64,
111 pub stdout: CheckOutput,
112 pub stderr: CheckOutput,
113 pub failure: Option<CheckFailure>,
114}
115#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
116#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
117pub struct CheckOutput {
118 pub text: String,
119 pub bytes_seen: u64,
120 pub truncated: bool,
121 pub complete: bool,
123}
124#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
125#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
126pub struct CheckFailure {
127 pub operation: CheckOperation,
128 pub os_code: Option<i32>,
129}
130#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
131#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
132#[serde(rename_all = "snake_case")]
133pub enum CheckOperation {
134 Spawn,
135 Capture,
136 Wait,
137 Terminate,
138}
139#[cfg(any(
140 windows,
141 target_os = "linux",
142 target_os = "android",
143 target_os = "macos",
144 target_os = "ios",
145 target_os = "freebsd",
146 target_os = "dragonfly",
147 target_os = "netbsd"
148))]
149impl CheckFailure {
150 fn io(operation: CheckOperation, error: std::io::Error) -> Self {
151 Self {
152 operation,
153 os_code: error.raw_os_error(),
154 }
155 }
156}
157impl CheckResult {
158 fn pending(command: CheckCommand) -> Self {
159 Self {
160 command,
161 outcome: CheckOutcome::NotRun,
162 exit_code: None,
163 duration_ms: 0,
164 stdout: CheckOutput::default(),
165 stderr: CheckOutput::default(),
166 failure: None,
167 }
168 }
169}
170impl ValidatePlanQuery {
171 pub(crate) fn available(engine: &Engine) -> bool {
172 process::CheckProcess::supported() && engine.workspace().execution_root().is_some()
173 }
174 pub fn execute(self, engine: &Engine) -> Result<ValidationReport, EngineError> {
175 let _operation = engine.operation();
176 self.execute_in(engine)
177 }
178 pub(crate) fn execute_in(self, engine: &Engine) -> Result<ValidationReport, EngineError> {
179 self.validate()?;
180 let root = engine
181 .workspace()
182 .execution_root()
183 .ok_or(EngineError::ValidationUnavailable)?;
184 if !process::CheckProcess::supported() {
185 return Err(EngineError::ValidationUnavailable);
186 }
187 let (receipt, baseline, run) = engine.plans().validation(&self.plan_id, Instant::now())?;
188 baseline.validate(engine).map_err(|error| match error {
189 EngineError::StaleQuery | EngineError::StaleSource { .. } => EngineError::StalePlan,
190 other => other,
191 })?;
192 let before = ValidationInputs::capture(engine, &self.extra_inputs, &baseline)?;
193 if !before.matches_baseline(&baseline)
195 || before != ValidationInputs::capture(engine, &self.extra_inputs, &baseline)?
196 {
197 return Err(EngineError::StalePlan);
198 }
199 let mut report = ValidationReport::new(
200 receipt,
201 run,
202 &before,
203 self.extra_inputs.clone(),
204 self.checks,
205 );
206 report.preflight(self.budget.max_bytes)?;
207 engine
208 .plans()
209 .reserve_validation(&self.plan_id, self.budget.max_bytes)?;
210 let started = Instant::now();
211 let deadline = started + Duration::from_millis(self.budget.timeout_ms);
212 let limit = self.budget.max_bytes / (report.checks.len() * 16);
213 for check in &mut report.checks {
214 if engine.cancellation().is_some_and(|c| c.is_cancelled()) {
215 check.outcome = CheckOutcome::Cancelled;
216 break;
217 }
218 if Instant::now() >= deadline {
219 check.outcome = CheckOutcome::TimedOut;
220 break;
221 }
222 if ValidationInputs::capture(engine, &self.extra_inputs, &baseline)
224 .is_ok_and(|current| current == before)
225 {
226 *check = process::CheckProcess::run(
227 &check.command,
228 root,
229 deadline,
230 limit,
231 engine.cancellation(),
232 );
233 } else {
234 break;
235 }
236 }
237 let observed = engine.without_cancellation();
239 match ValidationInputs::capture(&observed, &self.extra_inputs, &baseline) {
240 Ok(after) => {
241 report.source_state = if after == before {
242 ValidationSourceState::Unchanged
243 } else {
244 ValidationSourceState::Changed
245 };
246 report.after = Some(after.identity());
247 }
248 Err(_) => report.source_state = ValidationSourceState::Unavailable,
249 }
250 report.passed = report.source_state == ValidationSourceState::Unchanged
251 && report
252 .checks
253 .iter()
254 .all(|check| check.outcome == CheckOutcome::Passed);
255 report.fit(self.budget.max_bytes);
256 engine.touched();
258 engine
259 .plans()
260 .record_validation(&self.plan_id, report.clone());
261 Ok(report)
262 }
263 fn validate(&self) -> Result<(), EngineError> {
264 self.budget.validate()?;
265 if self.checks.is_empty() || self.checks.len() > 4 || self.extra_inputs.len() > 32 {
266 return Err(EngineError::InvalidValidation);
267 }
268 let mut bytes = 0usize;
269 for check in &self.checks {
270 if check.name.is_empty()
271 || check.name.len() > 128
272 || check.program.is_empty()
273 || check.program.contains('\0')
274 || check.args.len() > 64
275 || check.args.iter().any(|arg| arg.contains('\0'))
276 {
277 return Err(EngineError::InvalidValidation);
278 }
279 bytes = bytes
280 .saturating_add(check.name.len())
281 .saturating_add(check.program.len())
282 .saturating_add(check.args.iter().map(String::len).sum::<usize>());
283 }
284 if bytes > 8192 {
285 return Err(EngineError::InvalidValidation);
286 }
287 for path in &self.extra_inputs {
288 if path.as_os_str().is_empty()
289 || path.is_absolute()
290 || path
291 .components()
292 .any(|c| !matches!(c, std::path::Component::Normal(_)))
293 {
294 return Err(EngineError::InvalidValidation);
295 }
296 }
297 Ok(())
298 }
299}
300#[derive(Debug, PartialEq, Eq, Serialize)]
301struct ValidationInputs {
302 files: BTreeMap<RelPath, ContentId>,
303 #[serde(skip_serializing_if = "Option::is_none")]
304 moves: Option<baseline::MoveObservation>,
305}
306impl ValidationInputs {
307 fn capture(
308 engine: &Engine,
309 extra: &[RelPath],
310 baseline: &baseline::ValidationBaseline,
311 ) -> Result<Self, EngineError> {
312 let (_, current) = QuerySnapshot::capture(engine)?;
313 let mut files = BTreeMap::new();
314 for path in engine.workspace().files()? {
315 engine.check_read()?;
316 let relative: RelPath = engine.workspace().relative(&path).into();
317 if relative
318 .components()
319 .next()
320 .is_some_and(|c| c.as_os_str() == ".vvv")
321 {
322 continue;
323 }
324 let bytes = engine.workspace().vfs().read_bytes(&path)?;
325 files.insert(relative, ContentId::of_bytes(&bytes));
326 }
327 for path in extra
328 .iter()
329 .chain(baseline.inputs().keys())
330 .chain(current.inputs().keys())
331 {
332 engine.check_read()?;
333 let bytes = engine
334 .workspace()
335 .vfs()
336 .read_bytes(&engine.workspace().absolute(path))?;
337 let content = ContentId::of_bytes(&bytes);
338 if files.get(path).is_some_and(|previous| previous != &content) {
339 return Err(EngineError::StalePlan);
340 }
341 files.insert(path.clone(), content);
342 }
343 Ok(Self {
344 files,
345 moves: baseline.observe(engine)?,
346 })
347 }
348 fn matches_baseline(&self, baseline: &baseline::ValidationBaseline) -> bool {
349 baseline
350 .inputs()
351 .iter()
352 .all(|(path, content)| self.files.get(path) == Some(content))
353 && baseline.matches(self.moves.as_ref())
354 }
355 fn identity(&self) -> SnapshotId {
356 ContentId::of(&serde_json::to_string(self).expect("inputs serialize")).into()
357 }
358}
359impl ValidationReport {
360 fn new(
361 receipt: PlanReceipt,
362 run: u64,
363 inputs: &ValidationInputs,
364 extra_inputs: Vec<RelPath>,
365 checks: Vec<CheckCommand>,
366 ) -> Self {
367 Self {
368 plan_id: receipt.plan_id,
369 history_id: receipt.history_id,
370 run,
371 sources: receipt.files,
372 before: inputs.identity(),
373 after: None,
374 input_files: inputs.files.len(),
375 extra_inputs,
376 source_state: ValidationSourceState::Unavailable,
377 passed: false,
378 checks: checks.into_iter().map(CheckResult::pending).collect(),
379 }
380 }
381 fn preflight(&self, max_bytes: usize) -> Result<(), EngineError> {
382 let required_bytes = serde_json::to_vec(self)
384 .expect("report serializes")
385 .len()
386 .saturating_add(1024);
387 if required_bytes > max_bytes {
388 return Err(EngineError::OutputLimit {
389 max_bytes,
390 required_bytes,
391 });
392 }
393 Ok(())
394 }
395 fn fit(&mut self, max_bytes: usize) {
396 while serde_json::to_vec(self).expect("report serializes").len() > max_bytes {
397 let output = self
398 .checks
399 .iter_mut()
400 .flat_map(|check| [&mut check.stdout, &mut check.stderr])
401 .max_by_key(|output| output.text.len())
402 .expect("nonempty checks");
403 assert!(!output.text.is_empty(), "preflight reserved metadata");
404 let mut end = output.text.len() / 2;
405 while !output.text.is_char_boundary(end) {
406 end -= 1;
407 }
408 output.text.truncate(end);
409 output.truncated = true;
410 }
411 }
412}
413impl crate::report::Document {
414 pub(crate) fn validation(report: &ValidationReport) -> Self {
415 use crate::protocol::display::{Line, Role};
416 let mut doc = Self::new();
417 doc.body([Line::single(
418 Role::Strong,
419 if report.passed {
420 "Validation passed"
421 } else {
422 "Validation did not pass"
423 },
424 )]);
425 for check in &report.checks {
426 let status = match check.outcome {
427 CheckOutcome::NotRun => "not run",
428 CheckOutcome::Passed => "passed",
429 CheckOutcome::Failed => "failed",
430 CheckOutcome::TimedOut => "timed out",
431 CheckOutcome::Cancelled => "cancelled",
432 CheckOutcome::Error => "could not complete",
433 };
434 doc.body([Line::single(Role::Plain, &check.command.name)
435 .and(Role::Plain, format!(": {status}"))]);
436 doc.body(
437 check
438 .stdout
439 .text
440 .lines()
441 .chain(check.stderr.text.lines())
442 .map(|line| Line::single(Role::Plain, line)),
443 );
444 }
445 if report.source_state != ValidationSourceState::Unchanged {
446 doc.notes([Line::single(Role::Dim, "Source inputs changed or could not be verified; these results do not validate the current workspace")]);
447 }
448 doc
449 }
450}