Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

14.8 KB
Raw Blame
//! Contracts and result types for the commands in `cmd/diagnostics.rs`: the crash reports on
//! this computer (#10909), the profiler and the validation mode.

use std::borrow::Cow;

use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
use serde::de::Error as _;
use serde::{Deserialize, Deserializer, Serialize};
use serde_json::{Map, Value, json};

/// List this computer's crash reports, newest first. They stay on this computer and are never
/// sent anywhere. Read one with `diagnostics.crash_report`; reproduce one with
/// `solidcraft-cli crashes replay <id>`.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct CrashReportsParams {
    /// How many reports to list, newest first. Default: 20; at most 1000 are listed, whatever
    /// the limit.
    #[serde(default)]
    pub limit: Option<u64>,
}

/// What `diagnostics.crash_reports` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct CrashReportList {
    /// The crash report folder on this computer.
    pub dir: String,
    /// The reports, newest first.
    pub reports: Vec<crate::crash::Summary>,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// Read one crash report: the whole report as it was saved, with the paths of its files.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct CrashReportParams {
    /// The report's id, as `diagnostics.crash_reports` lists it.
    pub id: String,
}

/// What `diagnostics.crash_report` returns: the report as saved, with where its files are. A
/// report from an earlier release may lack some of these fields, and a report can carry more
/// (`startup_phase`, `native`).
#[derive(Debug, Serialize)]
pub struct CrashReport {
    /// The report's fields.
    #[serde(flatten)]
    pub report: Map<String, Value>,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

impl JsonSchema for CrashReport {
    fn schema_name() -> Cow<'static, str> {
        "CrashReport".into()
    }
    fn json_schema(_: &mut SchemaGenerator) -> Schema {
        let path =
            |what: &str| json!({"description": format!("Where the report's {what} is on this computer; only when it has one."), "type": "string"});
        json_schema!({
            "description": "A crash report as saved, with where its files are. A report from an earlier release may lack some fields, and a report can carry more.",
            "type": "object",
            "properties": {
                "id": {"description": "The report's id.", "type": "string"},
                "kind": {"description": "command_panic, panic, kernel_panic_recovered or unclean_exit.", "type": "string"},
                "signature": {"description": "What tells this crash apart from others, so a repeat counts against the same report."},
                "count": {"description": "How many times it happened.", "type": "integer", "minimum": 0},
                "first_seen": {"description": "When it was first recorded (UTC). An unclean exit is recorded at a later launch."},
                "last_seen": {"description": "When it was last recorded (UTC)."},
                "app": {"description": "The app's version, commit and build date."},
                "system": {"description": "The operating system, architecture and graphics environment."},
                "session": {"description": "How long the app had been running."},
                "message": {"description": "The internal error's message."},
                "location": {"description": "Where in the code it happened."},
                "thread": {"description": "The thread it happened on."},
                "backtrace": {"description": "The stack, one frame `symbol (file:line)` each."},
                "command": {"description": "The command running when it happened, with its parameters, if one was."},
                "base": {"description": "What the replay starts from."},
                "recent_commands": {"description": "The commands run before it."},
                "files": {"description": "The files saved with the report, by what they are."},
                "reproduce": {"description": "The command line that replays the crash, when it can be."},
                "notes": {"description": "What the report could not record, and why."},
                "path": {"description": "The report's folder on this computer.", "type": "string"},
                "design_path": path("design"),
                "replay_path": path("replay (`solidcraft-cli run <replay_path> --in <design_path>`)"),
                "minidump_path": path("minidump"),
                "param_warnings": {"description": "In the warn parameter-check mode: what the call's parameters got wrong.", "type": "array", "items": {"type": "string"}}
            }
        })
    }
}

/// Delete one crash report, or all of them.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct CrashReportsClearParams {
    /// The report to delete, as `diagnostics.crash_reports` lists it. Default: every report. An
    /// id that names no report deletes nothing.
    #[serde(default)]
    pub id: Option<String>,
}

/// What `diagnostics.crash_reports.clear` returns.
#[derive(Debug, Serialize, JsonSchema)]
pub struct CrashReportsCleared {
    /// How many reports were deleted.
    pub deleted: usize,
    /// In the warn parameter-check mode: what the call's parameters got wrong.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub param_warnings: Vec<String>,
}

/// Check that crash reports work, by crashing on purpose. Only when the SOLIDCRAFT_CRASH_TEST
/// environment variable is set.
#[derive(Debug, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct CrashTestParams {
    /// What to break.
    pub mode: CrashTestMode,
}

/// What `diagnostics.crash_test` breaks.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum CrashTestMode {
    /// An internal error in this command, caught: the design is unchanged.
    Panic,
    /// An internal error inside the geometry kernel, caught.
    Kernel,
    /// The app ends at once; the report is made at the next start.
    Abort,
}

impl<'de> Deserialize<'de> for CrashTestMode {
    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
        match Value::deserialize(d)? {
            Value::String(s) if s == "panic" => Ok(CrashTestMode::Panic),
            Value::String(s) if s == "kernel" => Ok(CrashTestMode::Kernel),
            Value::String(s) if s == "abort" => Ok(CrashTestMode::Abort),
            _ => Err(D::Error::custom("must be panic, kernel or abort")),
        }
    }
}

/// What `diagnostics.crash_test` would return. It never succeeds: it ends in an internal error
/// that is caught and reported (`panic`, `kernel`), or it ends the app (`abort`).
#[derive(Debug, Serialize, JsonSchema)]
pub struct CrashTestResult {}

/// `true`, `false` or null, with the handler's message for anything else.
fn flag<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Option<bool>, D::Error> {
    match Value::deserialize(d)? {
        Value::Null => Ok(None),
        Value::Bool(b) => Ok(Some(b)),
        _ => Err(serde::de::Error::custom("must be true or false")),
    }
}

/// A row count, with the handler's message for anything else.
fn rows<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Option<u64>, D::Error> {
    match Value::deserialize(d)? {
        Value::Null => Ok(None),
        v => v.as_u64().map(Some).ok_or_else(|| serde::de::Error::custom("must be a whole number of rows (0: all)")),
    }
}

/// A file path, with the handler's message for anything else.
fn path<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Option<String>, D::Error> {
    match Value::deserialize(d)? {
        Value::Null => Ok(None),
        Value::String(s) if !s.trim().is_empty() && s.len() < 4096 => Ok(Some(s)),
        _ => Err(serde::de::Error::custom("must be a file path")),
    }
}

/// What `diagnostics.profile` should do besides reporting.
#[derive(Debug, Default, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ProfileParams {
    /// Start (`true`) or stop (`false`) recording, after the report is taken.
    #[serde(default, deserialize_with = "flag")]
    pub enabled: Option<bool>,
    /// Forget what was recorded, after the report is taken.
    #[serde(default, deserialize_with = "flag")]
    pub reset: Option<bool>,
    /// How many rows to return, the most self time first (default 20; 0: all of them).
    #[serde(default, deserialize_with = "rows")]
    pub top: Option<u64>,
    /// Write the recorded spans here as a Chrome trace-event file (chrome://tracing, Perfetto).
    #[serde(default, deserialize_with = "path")]
    pub trace: Option<String>,
}

/// One category's share of the recorded self time.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ProfileCategory {
    /// `solidcore` (the kernel's own calls), `kernel`, `feature`, `doc`, `command`, `import`, `io`.
    pub category: String,
    pub self_ms: f64,
    /// Of all recorded self time, 0–1.
    pub share: f64,
}

/// One span name's aggregate.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ProfileRow {
    pub category: String,
    pub name: String,
    pub count: u64,
    /// Its time, counting only its outermost occurrence on each thread's stack.
    pub total_ms: f64,
    /// Its time less the time of the spans inside it.
    pub self_ms: f64,
    /// Its longest single run.
    pub max_ms: f64,
}

/// What the profiler recorded: the reply of `diagnostics.profile`, and an import's `profile`.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ProfileReport {
    /// The profiler is compiled into this build (the apps' `profile` feature).
    pub compiled: bool,
    /// It is recording (after this call's `enabled`).
    pub enabled: bool,
    /// Wall time the report covers.
    pub wall_ms: f64,
    /// Spans recorded.
    pub spans: u64,
    /// Spans left out of the trace (past its cap); they are in the rows.
    pub dropped: u64,
    /// Self time per category, the most first.
    pub by_category: Vec<ProfileCategory>,
    /// The span names with the most self time, the most first.
    pub rows: Vec<ProfileRow>,
    /// Span names recorded (rows lists `top` of them).
    pub rows_total: usize,
    /// Where the Chrome trace was written, when `trace` asked for one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub trace: Option<String>,
}

fn ms(d: std::time::Duration) -> f64 {
    (d.as_secs_f64() * 1e6).round() / 1e3
}

impl ProfileReport {
    /// `report` with its `top` rows of most self time (0: all of them).
    pub fn new(report: &solidcraft_profile::Report, top: usize) -> ProfileReport {
        let sorted = report.sorted();
        let all: f64 = report.rows.iter().map(|r| r.self_time.as_secs_f64()).sum();
        let by_category = report
            .by_category()
            .into_iter()
            .map(|(c, d)| ProfileCategory {
                category: c.to_string(),
                self_ms: ms(d),
                share: if all > 0.0 { (d.as_secs_f64() / all * 1000.0).round() / 1000.0 } else { 0.0 },
            })
            .collect();
        let n = if top == 0 { sorted.len() } else { top.min(sorted.len()) };
        let rows = sorted
            .iter()
            .take(n)
            .map(|r| ProfileRow {
                category: r.category.to_string(),
                name: r.name.to_string(),
                count: r.count,
                total_ms: ms(r.total),
                self_ms: ms(r.self_time),
                max_ms: ms(r.max),
            })
            .collect();
        ProfileReport {
            compiled: report.compiled,
            enabled: report.enabled,
            wall_ms: ms(report.wall),
            spans: (report.events as u64).saturating_add(report.dropped),
            dropped: report.dropped,
            by_category,
            rows,
            rows_total: sorted.len(),
            trace: None,
        }
    }
}

/// A validation mode by name, with the handler's message for anything else.
fn validation_mode<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Option<ValidationMode>, D::Error> {
    match Value::deserialize(d)? {
        Value::Null => Ok(None),
        Value::String(s) => ValidationMode::parse(&s).map(Some).ok_or_else(|| serde::de::Error::custom(VALIDATION_MODES)),
        _ => Err(serde::de::Error::custom(VALIDATION_MODES)),
    }
}

/// What a `mode` that names no validation mode is told.
pub(crate) const VALIDATION_MODES: &str = "must be each_step, each_feature or off";

/// When SMLib's full check runs while features are computed.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ValidationMode {
    /// After every sweep, boolean and blend inside a feature: a step whose result fails the
    /// check fails the feature there.
    EachStep,
    /// Once per feature (the default): each body the feature makes or changes is checked before
    /// it is kept, and a body the check refuses fails the feature with the check's reason.
    EachFeature,
    /// Never (experimental): a body the check would refuse is kept.
    Off,
}

impl ValidationMode {
    fn parse(id: &str) -> Option<ValidationMode> {
        solidcraft_kernel::Validation::parse(id).map(ValidationMode::from)
    }
}

impl From<solidcraft_kernel::Validation> for ValidationMode {
    fn from(v: solidcraft_kernel::Validation) -> Self {
        match v {
            solidcraft_kernel::Validation::EachStep => ValidationMode::EachStep,
            solidcraft_kernel::Validation::EachFeature => ValidationMode::EachFeature,
            solidcraft_kernel::Validation::Off => ValidationMode::Off,
        }
    }
}

/// Read, or set, when SMLib's full check runs on the features computed from now on.
#[derive(Debug, Default, Deserialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct ValidationParams {
    /// The mode to compute features under from now on. Default: leave it as it is. The results
    /// already there stand until their features are computed again (`timeline.compute_all`).
    #[serde(default, deserialize_with = "validation_mode")]
    pub mode: Option<ValidationMode>,
}

/// The reply of `diagnostics.validation`.
#[derive(Debug, Serialize, JsonSchema)]
pub struct ValidationReply {
    /// The mode features are computed under now.
    pub mode: ValidationMode,
    /// The mode before this call.
    pub previous: ValidationMode,
}

/// Tests that switch the process-wide profiler on, off or reset it run one at a time.
#[cfg(test)]
pub(crate) static PROFILE_TESTS: std::sync::Mutex<()> = std::sync::Mutex::new(());

#[cfg(test)]
#[path = "diagnostics_tests.rs"]
mod tests;