use std::path::{Path, PathBuf};
use std::sync::Arc;
pub use dive_trace::mutate::{ControlMode, Mutant};
pub use dive_trace::{
Check, DEADLOCK_UNSUPPORTED, Ending, Failure, InitialErrorStage, InitialInvariantClass, Report,
State, Trace, TraceDoc, Validation, ValidationRunError,
};
use serde_json::{Value, json};
use crate::ApiError;
pub const TRACE_SCHEMA_VERSION: u32 = crate::REPORT_SCHEMA_VERSION;
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct TraceOptions {
pub inputs: Option<dive_eval::inputs::RecordedInputs>,
pub compat_tlc: bool,
pub symmetry_liveness: Option<dive_model::SymmetryLiveness>,
pub no_deadlock: bool,
pub run: Option<(i64, usize)>,
pub library_paths: Vec<PathBuf>,
pub module_paths: Vec<PathBuf>,
}
#[derive(Debug, Clone)]
pub struct SpecModel {
model: dive_model::Model,
model_values: Vec<String>,
session: dive_trace::Session,
recipe: dive_model::Recipe,
}
pub(crate) fn make_run_config(
model: &dive_model::Model,
seed: i64,
fp_index: usize,
) -> dive_eval::RunConfig {
dive_eval::RunConfig {
deadlock: model.settings.check_deadlock,
workers: 1,
seed,
fingerprint: i64::from_ne_bytes(
dive_value::fp64::POLYS
.get(fp_index)
.copied()
.unwrap_or(0)
.to_ne_bytes(),
),
install: std::env::current_exe()
.map(|path| path.display().to_string())
.unwrap_or_default(),
}
}
impl SpecModel {
pub fn load(spec: &Path, cfg: &Path, opts: &TraceOptions) -> Result<Self, ApiError> {
Self::load_hosted(spec, cfg, opts, None)
}
pub(crate) fn load_hosted(
spec: &Path,
cfg: &Path,
opts: &TraceOptions,
host: Option<Arc<dyn dive_eval::Host>>,
) -> Result<Self, ApiError> {
let sema = sema_options(opts);
let shown = spec.display().to_string();
let analysis = dive_sema::analyze_file(spec, &sema).map_err(|error| ApiError::Io {
path: shown.clone(),
error,
})?;
let text = std::fs::read(cfg).map_err(|error| ApiError::Io {
path: cfg.display().to_string(),
error,
})?;
let (_, parsed) = dive_config::parse_bytes(&text);
Self::bind_hosted(&shown, &analysis, parsed, opts, host)
}
pub fn from_source(
file: &str,
source: &str,
cfg: &str,
opts: &TraceOptions,
) -> Result<Self, ApiError> {
let analysis = dive_sema::analyze_source(file, source, &sema_options(opts));
Self::bind(file, &analysis, dive_config::parse(cfg), opts)
}
fn bind(
file: &str,
analysis: &dive_sema::Analysis,
cfg: dive_config::ConfigParse,
opts: &TraceOptions,
) -> Result<Self, ApiError> {
Self::bind_hosted(file, analysis, cfg, opts, None)
}
#[allow(
clippy::too_many_lines,
reason = "one ordered startup transaction retains source, host, replay cursor and config ownership"
)]
fn bind_hosted(
file: &str,
analysis: &dive_sema::Analysis,
cfg: dive_config::ConfigParse,
opts: &TraceOptions,
owned_host: Option<Arc<dyn dive_eval::Host>>,
) -> Result<Self, ApiError> {
if owned_host.is_some() && opts.inputs.is_some() {
return Err(ApiError::Unsupported {
feature: "owned simulation external input replay is not implemented".into(),
});
}
if !analysis.accepted() {
return Err(ApiError::Rejected {
message: format!("{file} has errors; `dive analyze` lists them"),
});
}
let Some(cfg) = cfg.into_config() else {
return Err(ApiError::Rejected {
message: "the configuration has errors; `dive parse --config` lists them"
.to_owned(),
});
};
let ir = dive_ir::lower(analysis).map_err(|e| ApiError::Unsupported {
feature: e.to_string(),
})?;
let ir = Arc::new(ir);
dive_eval::validate_ir(&ir).map_err(|error| ApiError::Unsupported {
feature: error.to_string(),
})?;
if let Some(feature) = dive_model::transformed_randomness(&ir, &cfg) {
return Err(ApiError::Unsupported {
feature: feature.to_owned(),
});
}
let mode = if opts.compat_tlc {
dive_stdlib::random::RandomMode::Tlc
} else {
dive_stdlib::random::RandomMode::Dive
};
let streams = match opts.run {
Some((seed, fp_index)) => {
if fp_index >= dive_value::fp64::POLYS.len() {
return Err(ApiError::Rejected {
message: format!(
"fingerprint polynomial index {fp_index} is out of range (0..{})",
dive_value::fp64::POLYS.len()
),
});
}
Some(dive_stdlib::random::Streams::new(seed, mode))
}
None => None,
};
let replay = opts
.inputs
.as_ref()
.map(|inputs| dive_eval::inputs::InputReplay::new(inputs.clone()).map(Arc::new))
.transpose()
.map_err(|error| ApiError::Unsupported {
feature: error.message,
})?;
let host = streams.map(|s| {
let host = dive_stdlib::host::RunHost::new(s, None);
Arc::new(if let Some(replay) = &replay {
host.with_inputs(replay.clone())
} else {
host
})
});
let mut bind_opts = dive_model::BindOptions {
no_deadlock: opts.no_deadlock,
host: owned_host
.or_else(|| host.clone().map(|h| -> Arc<dyn dive_eval::Host> { h }))
.or_else(|| {
replay
.clone()
.map(|replay| -> Arc<dyn dive_eval::Host> { replay })
}),
..if opts.compat_tlc {
dive_model::BindOptions::tlc()
} else {
dive_model::BindOptions::dive()
}
};
if let Some(inputs) = &opts.inputs {
bind_opts.eval.host_access = inputs.grants;
}
if let Some(policy) = opts.symmetry_liveness {
bind_opts.symmetry_liveness = policy;
}
let model_values = cfg.model_values.clone();
let recipe =
dive_model::Recipe::new(ir.clone(), cfg.clone(), bind_opts.eval, opts.no_deadlock)
.with_symmetry_liveness(bind_opts.symmetry_liveness);
let bound = on_big_stack(move || dive_model::bind(ir, &cfg, &bind_opts))?;
if let Some(replay) = &replay {
replay
.finish_binding()
.map_err(|error| ApiError::Unsupported {
feature: error.message,
})?;
}
let mut run_config = None;
if let (Ok(model), Some((seed, fp_index))) = (&bound, opts.run) {
model.evaluator.intern_checker_names();
let config = make_run_config(model, seed, fp_index);
model.evaluator.intern_bfs_config(&config);
if let Some(host) = &host {
host.set_config(Some(config.clone()));
}
run_config = Some(config);
}
match bound {
Ok(model) => Ok(Self {
model,
model_values,
recipe: recipe.clone(),
session: {
let session = dive_trace::Session::new(
recipe.clone(),
run_config.or_else(|| {
host.as_ref()
.and_then(|host| dive_eval::Host::config(&**host))
}),
);
if let Some(inputs) = &opts.inputs {
session.with_inputs(inputs.clone())
} else {
session
}
},
}),
Err(f) => match &f.error.kind {
dive_model::ErrorKind::Unsupported { feature } => Err(ApiError::Unsupported {
feature: feature.clone(),
}),
_ => Err(ApiError::Rejected {
message: f.error.to_string(),
}),
},
}
}
#[must_use]
pub fn model(&self) -> &dive_model::Model {
&self.model
}
pub(crate) fn preparation_model(
&self,
seed: i64,
mode: dive_stdlib::random::RandomMode,
control: Arc<dyn dive_eval::HostControl>,
) -> Result<dive_model::Model, String> {
let host = Arc::new(dive_stdlib::host::RunHost::new(
dive_stdlib::random::Streams::new(seed, mode),
None,
));
let model = on_big_stack(|| self.recipe.bind_next_fallible(host.clone(), Some(control)))
.map_err(|error| error.to_string())?
.map_err(|error| error.to_string())?;
if let Some(config) = self.model.evaluator.host().and_then(|host| host.config()) {
model.evaluator.intern_checker_names();
model.evaluator.intern_bfs_config(&config);
host.set_config(Some(config));
}
Ok(model)
}
#[must_use]
pub fn model_values(&self) -> &[String] {
&self.model_values
}
#[must_use]
pub fn validate(&self, doc: &TraceDoc) -> Report {
self.read(doc).0
}
pub(crate) fn validate_mode(
&self,
doc: &TraceDoc,
control: Arc<dyn dive_eval::HostControl>,
) -> Result<Report, ValidationRunError> {
on_big_stack(|| {
self.session
.read_controlled(doc, control)
.map(|(report, _)| report)
})
.map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
}
pub(crate) fn validate_sample_mode(
&self,
doc: &TraceDoc,
control: Arc<dyn dive_eval::HostControl>,
) -> Result<Report, ValidationRunError> {
on_big_stack(|| {
if doc.ending == Some(Ending::Behavior) {
self.session.read_sampled(doc, Some(control))
} else if doc.ending == Some(Ending::Deadlock) {
self.session.read_sampled_deadlock(doc, Some(control))
} else {
self.session.read_controlled(doc, control)
}
.map(|(report, _)| report)
})
.map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
}
pub fn try_validate_sample(&self, doc: &TraceDoc) -> Result<Report, ValidationRunError> {
on_big_stack(|| {
if doc.ending == Some(Ending::Deadlock) {
self.session.read_sampled_deadlock(doc, None)
} else {
self.session.read_sampled(doc, None)
}
.map(|(report, _)| report)
})
.map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
}
#[must_use]
pub fn read(&self, doc: &TraceDoc) -> (Report, Option<Trace>) {
on_big_stack(|| {
let (report, plain) = self.session.read(doc);
let trace = plain.and_then(|doc| Trace::decode(&self.model, &doc).ok());
(report, trace)
})
.unwrap_or_else(|e| (thread_failed(&e, doc.states.len()), None))
}
pub fn try_validate(&self, doc: &TraceDoc) -> Result<Report, ValidationRunError> {
self.try_read(doc).map(|(report, _)| report)
}
pub fn try_read(&self, doc: &TraceDoc) -> Result<(Report, Option<Trace>), ValidationRunError> {
if !matches!(
doc.ending,
Some(
Ending::TemporalStateError { .. }
| Ending::TemporalSourceError { .. }
| Ending::NextStateError { .. }
| Ending::ViewSourceError { .. }
| Ending::CandidateStateError { .. }
| Ending::PartialNext { .. }
| Ending::PartialInit { .. }
)
) {
return Ok(self.read(doc));
}
on_big_stack(|| {
let (report, plain) = self.session.try_read(doc)?;
let trace = plain.and_then(|doc| Trace::decode(&self.model, &doc).ok());
Ok((report, trace))
})
.map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
}
pub fn initial_invariant_class(
&self,
doc: &TraceDoc,
control: Option<Arc<dyn dive_eval::HostControl>>,
) -> Result<(Report, Option<dive_trace::InitialInvariantClass>), ValidationRunError> {
on_big_stack(|| self.session.initial_invariant_class(doc, control))
.map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
}
pub fn invariant_error_class(
&self,
doc: &TraceDoc,
control: Option<Arc<dyn dive_eval::HostControl>>,
) -> Result<(Report, Option<dive_trace::InvariantErrorClass>), ValidationRunError> {
on_big_stack(|| self.session.invariant_error_class(doc, control))
.map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
}
pub fn initial_error_stage(
&self,
control: Option<Arc<dyn dive_eval::HostControl>>,
) -> Result<(Report, Option<dive_trace::InitialErrorStage>), ValidationRunError> {
on_big_stack(|| self.session.initial_error_stage(control))
.map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
}
#[must_use]
pub fn validate_trace(&self, trace: &Trace) -> Report {
on_big_stack(|| {
for state in &trace.states {
for value in state.iter().flatten() {
if let Err(error) = value.validate_names(&self.model.names) {
return thread_failed(
&ApiError::Unsupported {
feature: error.to_string(),
},
trace.states.len(),
);
}
}
}
match trace.to_doc(&self.model) {
Ok(doc) => self.session.read(&doc).0,
Err(message) => thread_failed(&ApiError::Rejected { message }, trace.states.len()),
}
})
.unwrap_or_else(|e| thread_failed(&e, trace.states.len()))
}
#[must_use]
pub fn mutants(&self, trace: &Trace) -> Vec<Mutant> {
self.mutants_with_mode(trace, ControlMode::ShortestBfs)
}
#[must_use]
pub fn mutants_with_mode(&self, trace: &Trace, mode: ControlMode) -> Vec<Mutant> {
on_big_stack(|| dive_trace::mutate::mutants_with_mode(&self.model, trace, mode))
.unwrap_or_default()
}
pub fn to_doc(&self, trace: &Trace) -> Result<TraceDoc, ApiError> {
trace
.to_doc(&self.model)
.map_err(|message| ApiError::Rejected { message })
}
}
fn sema_options(opts: &TraceOptions) -> dive_sema::Options {
dive_sema::Options {
search: dive_sema::SearchPath {
library_paths: opts.library_paths.clone(),
after_standard: opts.module_paths.clone(),
},
..dive_sema::Options::default()
}
}
fn thread_failed(e: &ApiError, length: usize) -> Report {
Report {
validation: Validation::Unsupported(format!("internal error: {e}")),
notes: Vec::new(),
length,
}
}
fn on_big_stack<T: Send>(f: impl FnOnce() -> T + Send) -> Result<T, ApiError> {
std::thread::scope(|s| {
std::thread::Builder::new()
.stack_size(dive_eval::RECOMMENDED_STACK)
.spawn_scoped(s, f)
.ok()
.and_then(|h| h.join().ok())
})
.ok_or_else(|| ApiError::Unsupported {
feature: "internal error: the evaluation thread could not run or panicked".to_owned(),
})
}
#[must_use]
pub fn report_json(report: &Report) -> Value {
let mut j = json!({
"schema_version": TRACE_SCHEMA_VERSION,
"command": "validate-trace",
"result": report.validation.kind(),
"length": report.length,
"notes": report.notes,
});
match &report.validation {
Validation::Invalid(f) => {
j["failure"] = json!({"state": f.state, "check": f.check.name(), "detail": f.detail});
}
Validation::Unsupported(u) => j["unsupported"] = Value::from(u.as_str()),
_ => {}
}
j
}
#[must_use]
pub fn render_report(report: &Report) -> String {
use std::fmt::Write as _;
let mut s = match &report.validation {
Validation::Valid => format!("valid: the {}-state trace validates\n", report.length),
Validation::Invalid(f) => format!(
"invalid: state {} of {} (numbered from 1, as TLC prints traces), check `{}`: {}\n",
f.state + 1,
report.length,
f.check.name(),
f.detail
),
Validation::Unsupported(u) => format!("unsupported: {u}\n"),
other => format!("{}\n", other.kind()),
};
for n in &report.notes {
let _ = writeln!(s, "note: {n}");
}
s
}
#[derive(Debug, Clone)]
pub struct Controls {
pub positive: Report,
pub dive_format: Option<Validation>,
pub mutants: Vec<(String, Validation)>,
}
impl Controls {
#[must_use]
pub fn positive_ok(&self) -> bool {
match &self.positive.validation {
Validation::Valid => true,
Validation::Unsupported(u) => u == dive_trace::DEADLOCK_UNSUPPORTED,
_ => false,
}
}
#[must_use]
pub fn failures(&self) -> Vec<String> {
let mut out = Vec::new();
if !self.positive_ok() {
out.push(format!(
"positive control: {}",
render_report(&self.positive).trim_end()
));
}
if let Some(v) = &self.dive_format
&& *v != self.positive.validation
{
out.push(format!(
"the trace in dive's format gives {}, not {}",
v.kind(),
self.positive.validation.kind()
));
}
if self.mutants.is_empty() {
out.push("no negative controls generated".to_owned());
}
for (name, v) in &self.mutants {
if !matches!(v, Validation::Invalid(_)) {
out.push(format!("mutant {name} is not rejected: {}", v.kind()));
}
}
out
}
}
impl SpecModel {
#[must_use]
pub fn controls(&self, doc: &TraceDoc) -> Controls {
self.controls_with_mode(doc, ControlMode::ShortestBfs)
}
#[must_use]
pub fn controls_with_mode(&self, doc: &TraceDoc, mode: ControlMode) -> Controls {
let (positive, trace) = self.read(doc);
let mut mutants = Vec::new();
let mut dive_format = None;
if let Some(trace) = trace.filter(|_| {
matches!(
positive.validation,
Validation::Valid | Validation::Unsupported(_)
)
}) {
dive_format = Some(match self.to_doc(&trace) {
Ok(d) => self.validate(&d).validation,
Err(e) => Validation::Unsupported(e.to_string()),
});
for m in self.mutants_with_mode(&trace, mode) {
let direct = self.validate_trace(&m.trace).validation;
let via_format = match self.to_doc(&m.trace) {
Ok(d) => self.validate(&d).validation,
Err(e) => Validation::Unsupported(e.to_string()),
};
let v = if matches!(direct, Validation::Invalid(_)) {
via_format
} else {
direct
};
mutants.push((m.name, v));
}
}
Controls {
positive,
dive_format,
mutants,
}
}
}