diff --git a/crates/engine/src/cmd/libraries.rs b/crates/engine/src/cmd/libraries.rs index ecc1c0b1e..4b04415de 100644 --- a/crates/engine/src/cmd/libraries.rs +++ b/crates/engine/src/cmd/libraries.rs @@ -1,65 +1,33 @@ //! Local material libraries: inspect/export files and copy exact revisions into a design. use super::CommandSpec; +use crate::schema::libraries::{ + LibraryApplied, LibraryApplyParams, LibraryExportParams, LibraryExported, LibraryInspectParams, LibraryInspected, LibraryTargets, +}; +use crate::schema::{TypedContract, output_schema_for}; use crate::{Result, Session, params::bad}; -use serde::Deserialize; use serde_json::{Value, json}; -use solidcraft_io::catalog::{Catalog, Definition, Provenance}; +use solidcraft_io::catalog::{Catalog, Definition}; + +const INSPECT_CONTRACT: TypedContract = TypedContract::new(); +const EXPORT_CONTRACT: TypedContract = TypedContract::new(); +const APPLY_CONTRACT: TypedContract = TypedContract::new(); pub static COMMANDS: &[CommandSpec] = &[ - CommandSpec::new("library.inspect", "Inspect Local Library", inspect).icon("inspect").noundo().doc_only() + CommandSpec::new("library.inspect", "Inspect Local Library", crate::checked!("library.inspect", inspect)).icon("inspect").noundo().doc_only() + .contract(&INSPECT_CONTRACT) + .output(output_schema_for::) .params("path: v1/v2 library JSON; returns validated catalog and exact entry revisions, without changing the design"), - CommandSpec::new("library.export", "Export Design Library", export).icon("export").noundo().doc_only() + CommandSpec::new("library.export", "Export Design Library", crate::checked!("library.export", export)).icon("export").noundo().doc_only() + .contract(&EXPORT_CONTRACT) + .output(output_schema_for::) .params("path: .json; id? (default user.local), name?, provenance?, overwrite? false, format? solidcraft-library/2 (default) | solidcraft-library/1 (refuses PBR/cards). Copies assigned looks and design-local physical definitions; never changes the design"), - CommandSpec::new("library.apply", "Apply Local Library Entry", apply).icon("import").enabled(super::not_in_sketch) + CommandSpec::new("library.apply", "Apply Local Library Entry", crate::checked!("library.apply", apply)).icon("import").enabled(super::not_in_sketch) + .contract(&APPLY_CONTRACT) + .output(output_schema_for::) .params("path, entry: qualified ID, revision: exact content SHA-256; targets?: {bodies?, faces?: [{body,point}], components?}; name?: physical material name on import. Copies values in one undo step; material conflicts are explicit"), ]; -#[derive(Deserialize)] -#[serde(deny_unknown_fields)] -struct Inspect { - path: String, -} -#[derive(Deserialize)] -#[serde(deny_unknown_fields)] -struct Export { - path: String, - #[serde(default = "default_id")] - id: String, - #[serde(default = "default_name")] - name: String, - #[serde(default)] - provenance: Provenance, - #[serde(default)] - overwrite: bool, - #[serde(default = "default_format")] - format: String, -} -fn default_format() -> String { - solidcraft_io::catalog::FORMAT.into() -} -fn default_id() -> String { - "user.local".into() -} -fn default_name() -> String { - "My library".into() -} -#[derive(Default, Deserialize, serde::Serialize)] -#[serde(deny_unknown_fields)] -struct Targets { - #[serde(default)] - bodies: Vec, - #[serde(default)] - faces: Vec, - #[serde(default)] - components: Vec, -} -#[derive(Deserialize, serde::Serialize)] -#[serde(deny_unknown_fields)] -struct Face { - body: String, - point: [f64; 3], -} -impl Targets { +impl LibraryTargets { fn validate(&self) -> Result<()> { let cmd = "library.apply"; if self.bodies.len().saturating_add(self.faces.len()).saturating_add(self.components.len()) > 1024 { @@ -79,35 +47,28 @@ impl Targets { self.bodies.is_empty() && self.faces.is_empty() && self.components.is_empty() } } -#[derive(Deserialize)] -#[serde(deny_unknown_fields)] -struct Apply { - path: String, - entry: String, - revision: String, - #[serde(default)] - targets: Targets, - name: Option, -} fn path(cmd: &str, value: &str) -> Result<()> { if value.is_empty() || value.len() > 4096 || value.chars().any(char::is_control) { return Err(bad(cmd, "invalid library path")); } solidcraft_io::vfs::check(value).map_err(|e| bad(cmd, e.to_string())) } +fn reply(cmd: &str, reply: impl serde::Serialize) -> Result { + serde_json::to_value(reply).map_err(|e| bad(cmd, e.to_string())) +} fn nested(s: &mut Session, id: &str, p: &Value) -> Result { crate::find_command(id).ok_or_else(|| bad("library.apply", "required assignment command is unavailable"))?.run_nested(s, p) } fn inspect(_s: &mut Session, p: &Value) -> Result { let cmd = "library.inspect"; - let request: Inspect = serde_json::from_value(p.clone()).map_err(|e| bad(cmd, e.to_string()))?; + let request: LibraryInspectParams = serde_json::from_value(p.clone()).map_err(|e| bad(cmd, e.to_string()))?; path(cmd, &request.path)?; let catalog = Catalog::read(&request.path).map_err(|e| bad(cmd, e.to_string()))?; - Ok(json!({"catalog":catalog})) + reply(cmd, LibraryInspected { catalog, param_warnings: Vec::new() }) } fn export(s: &mut Session, p: &Value) -> Result { let cmd = "library.export"; - let request: Export = serde_json::from_value(p.clone()).map_err(|e| bad(cmd, e.to_string()))?; + let request: LibraryExportParams = serde_json::from_value(p.clone()).map_err(|e| bad(cmd, e.to_string()))?; path(cmd, &request.path)?; if !request.path.to_ascii_lowercase().ends_with(".json") { return Err(bad(cmd, "library export path must end in .json")); @@ -129,11 +90,12 @@ fn export(s: &mut Session, p: &Value) -> Result { solidcraft_io::vfs::write(&request.path, &bytes) }; result.map_err(|e| bad(cmd, format!("could not export library: {e}")))?; - Ok(json!({"path":request.path,"entries":catalog.entries.len(),"bytes":bytes.len(),"catalog":catalog})) + let entries = catalog.entries.len(); + reply(cmd, LibraryExported { path: request.path, entries, bytes: bytes.len(), catalog, param_warnings: Vec::new() }) } fn apply(s: &mut Session, p: &Value) -> Result { let cmd = "library.apply"; - let request: Apply = serde_json::from_value(p.clone()).map_err(|e| bad(cmd, e.to_string()))?; + let request: LibraryApplyParams = serde_json::from_value(p.clone()).map_err(|e| bad(cmd, e.to_string()))?; path(cmd, &request.path)?; request.targets.validate()?; if request.entry.len() > 129 || request.revision.len() != 64 { @@ -205,7 +167,7 @@ fn apply(s: &mut Session, p: &Value) -> Result { json!({"material":name,"reused":reused,"bodies":request.targets.bodies}) } }; - Ok(json!({"entry":entry.id,"revision":entry.revision,"copied":true,"result":result})) + reply(cmd, LibraryApplied { entry: entry.id.clone(), revision: entry.revision.clone(), copied: true, result, param_warnings: Vec::new() }) } #[cfg(test)] diff --git a/crates/engine/src/cmd/libraries_tests.rs b/crates/engine/src/cmd/libraries_tests.rs index 50e0abadc..216a9fdf1 100644 --- a/crates/engine/src/cmd/libraries_tests.rs +++ b/crates/engine/src/cmd/libraries_tests.rs @@ -1,5 +1,5 @@ use super::*; -use solidcraft_io::catalog::{Definition, Entry, FORMAT, LibraryLook, LibraryMaterial}; +use solidcraft_io::catalog::{Definition, Entry, FORMAT, LibraryLook, LibraryMaterial, Provenance}; use std::sync::{ Arc, atomic::{AtomicU64, Ordering}, diff --git a/crates/engine/src/schema/libraries.rs b/crates/engine/src/schema/libraries.rs new file mode 100644 index 000000000..345ee1e3e --- /dev/null +++ b/crates/engine/src/schema/libraries.rs @@ -0,0 +1,270 @@ +//! Contracts and result types for the commands in `cmd/libraries.rs`: local material libraries +//! (#10938). The handlers read these same types, so the contract is exactly what they take; +//! like them, a contract refuses unknown keys. + +use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema}; +use serde::{Deserialize, Serialize}; +use serde_json::{Value, json}; +use solidcraft_io::catalog::{Catalog, FORMAT, Provenance, V1_FORMAT}; + +/// Read a local library file and check it, without changing the design. +#[derive(Debug, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct LibraryInspectParams { + /// The library file (`solidcraft-library/1` or `/2` JSON, at most 4 MiB). + pub path: String, +} + +/// Write the looks assigned in this design and its own physical materials to a library file. +/// The design is never changed. +#[derive(Debug, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct LibraryExportParams { + /// Where to write it: a `.json` file. + pub path: String, + /// The library's id, which qualifies each entry's id: lowercase letters, digits, `.`, `_` + /// and `-`, starting with a letter, at most 64. + #[serde(default = "default_id")] + pub id: String, + /// The library's name: 1 to 128 bytes, without surrounding spaces or control characters. + #[serde(default = "default_name")] + pub name: String, + /// Where the entries come from, saved with each entry. + #[serde(default)] + #[schemars(schema_with = "provenance_schema")] + pub provenance: Provenance, + /// Replace the file if it exists. Without it, an existing file is refused and left as it is. + #[serde(default)] + pub overwrite: bool, + /// The file format. `solidcraft-library/1` refuses a design whose looks or materials have + /// PBR or physical cards, before writing anything. + #[serde(default = "default_format")] + #[schemars(schema_with = "format_schema")] + pub format: String, +} + +fn default_id() -> String { + "user.local".into() +} + +fn default_name() -> String { + "My library".into() +} + +fn default_format() -> String { + FORMAT.into() +} + +/// Copy one library entry, at an exact revision, into this design in one undo step: an +/// appearance onto bodies, faces or components, or a physical material (assigned to bodies). +#[derive(Debug, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct LibraryApplyParams { + /// The library file. + pub path: String, + /// The entry's qualified id, as `library.inspect` lists it (at most 129 bytes). + pub entry: String, + /// The entry's revision, as `library.inspect` lists it: the SHA-256 of its content, 64 hex + /// digits. An entry whose content has changed since is refused. + pub revision: String, + /// What to copy it onto. An appearance needs at least one target; a physical material takes + /// bodies only, and with none it is only added to the design. + #[serde(default)] + pub targets: LibraryTargets, + /// For a physical material: the name to give it in this design (1 to 128 bytes). Default: + /// the entry's name. A material of that name already in the design is reused if it is the + /// same, and refused if it differs. An appearance entry refuses it. + pub name: Option, +} + +/// What a library entry is copied onto: at most 1024 targets in all. +#[derive(Debug, Default, Deserialize, Serialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct LibraryTargets { + /// Bodies, by name. + #[serde(default)] + pub bodies: Vec, + /// Faces, each by its body and a point on it (each coordinate finite and under 1e9 in size). + #[serde(default)] + pub faces: Vec, + /// Components, by name. + #[serde(default)] + pub components: Vec, +} + +/// A face, by its body and a point on it. +#[derive(Debug, Deserialize, Serialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct LibraryFace { + /// The body's name. + pub body: String, + /// A point on the face. + pub point: [f64; 3], +} + +/// What `library.inspect` returns. +#[derive(Debug, Serialize, JsonSchema)] +pub struct LibraryInspected { + /// The library as read and checked. + #[schemars(schema_with = "catalog_schema")] + pub catalog: Catalog, + /// 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, +} + +/// What `library.export` returns. +#[derive(Debug, Serialize, JsonSchema)] +pub struct LibraryExported { + /// The file written. + pub path: String, + /// How many entries it holds. + pub entries: usize, + /// Its size in bytes. + pub bytes: usize, + /// The library as written. + #[schemars(schema_with = "catalog_schema")] + pub catalog: Catalog, + /// 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, +} + +/// What `library.apply` returns. +#[derive(Debug, Serialize, JsonSchema)] +pub struct LibraryApplied { + /// The entry copied. + pub entry: String, + /// Its revision. + pub revision: String, + /// Always true: the entry's values were copied into the design, which keeps no link to the + /// file. + pub copied: bool, + /// What was done with it. + #[schemars(schema_with = "applied_schema")] + pub result: 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, +} + +fn provenance_schema(_: &mut SchemaGenerator) -> Schema { + // `provenance()` is an object, which a schema always takes. + Schema::try_from(provenance()).unwrap_or_else(|_| Schema::from(true)) +} + +fn provenance() -> Value { + let text = |what: &str, max: u32| json!({"description": format!("{what}: 1 to {max} bytes, without surrounding spaces or control characters."), "type": "string"}); + json!({ + "description": "Where a library entry comes from. Information only: the source URL is never fetched.", + "type": "object", + "properties": { + "license": text("Its licence, such as an SPDX expression", 128), + "author": text("Who made it", 256), + "source_url": text("Where it was published", 2048) + }, + "required": ["license"], + "additionalProperties": false + }) +} + +fn format_schema(_: &mut SchemaGenerator) -> Schema { + json_schema!({"type": "string", "enum": [FORMAT, V1_FORMAT]}) +} + +/// A look as a library saves it. +fn look() -> Value { + json!({ + "description": "A look: its name, colour and opacity, and a physically based response when it has one.", + "type": "object", + "properties": { + "name": {"type": "string"}, + "color": {"description": "Red, green and blue, 0 to 255.", "type": "array", "items": {"type": "integer", "minimum": 0, "maximum": 255}, "minItems": 3, "maxItems": 3}, + "opacity": {"type": "number", "minimum": 0, "maximum": 1}, + "pbr": {"description": "metallic (0 to 1), roughness (0.045 to 1) and dielectric_ior (1 to 3).", "type": "object"} + }, + "required": ["name", "color", "opacity"] + }) +} + +fn catalog_schema(_: &mut SchemaGenerator) -> Schema { + let definition = |kind: &str, value: Value| { + json!({ + "type": "object", + "properties": {"kind": {"type": "string", "enum": [kind]}, "value": value}, + "required": ["kind", "value"] + }) + }; + let material = json!({ + "description": "A physical material: its name and density, with its default look and a physical card when it has them.", + "type": "object", + "properties": { + "name": {"type": "string"}, + "density_g_cm3": {"type": "number", "exclusiveMinimum": 0}, + "appearance": look(), + "physical_card": {"description": "Its validated engineering data, as material.inspect shows it.", "type": "object"} + }, + "required": ["name", "density_g_cm3"] + }); + json_schema!({ + "description": "A local library: no network, external resources or links to a design.", + "type": "object", + "properties": { + "format": {"type": "string", "enum": [FORMAT, V1_FORMAT]}, + "id": {"description": "The library's id.", "type": "string"}, + "name": {"description": "The library's name.", "type": "string"}, + "entries": { + "type": "array", + "maxItems": 1024, + "items": { + "type": "object", + "properties": { + "id": {"description": "`/-`, as library.apply takes it.", "type": "string"}, + "revision": {"description": "The SHA-256 of the entry's content, 64 hex digits, as library.apply takes it.", "type": "string"}, + "provenance": provenance(), + "definition": {"anyOf": [definition("appearance", look()), definition("material", material)]} + }, + "required": ["id", "revision", "provenance", "definition"] + } + } + }, + "required": ["format", "id", "name", "entries"] + }) +} + +fn applied_schema(_: &mut SchemaGenerator) -> Schema { + let names = |what: &str| json!({"description": what, "type": "array", "items": {"type": "string"}}); + json_schema!({ + "anyOf": [ + { + "description": "An appearance: what appearance.assign assigned it to, and the look.", + "type": "object", + "properties": { + "bodies": names("The bodies."), + "faces": { + "description": "The faces, each by its body and the point given.", + "type": "array", + "items": {"type": "object", "properties": {"body": {"type": "string"}, "point": {"type": "array", "items": {"type": "number"}}}} + }, + "components": names("The components."), + "appearance": {"description": "The look assigned: name, colour (`#rrggbb`), opacity and pbr when it has one.", "type": ["object", "null"]} + }, + "required": ["bodies", "faces", "components", "appearance"] + }, + { + "description": "A physical material: its name in this design, whether one already there was reused, and the bodies it was assigned to.", + "type": "object", + "properties": { + "material": {"type": "string"}, + "reused": {"type": "boolean"}, + "bodies": names("The bodies.") + }, + "required": ["material", "reused", "bodies"] + } + ] + }) +} + +#[cfg(test)] +#[path = "libraries_tests.rs"] +mod tests; diff --git a/crates/engine/src/schema/libraries_tests.rs b/crates/engine/src/schema/libraries_tests.rs new file mode 100644 index 000000000..6d0478687 --- /dev/null +++ b/crates/engine/src/schema/libraries_tests.rs @@ -0,0 +1,99 @@ +use serde_json::{Value, json}; + +use super::{LibraryApplied, LibraryApplyParams, LibraryExportParams, LibraryExported, LibraryInspectParams, LibraryInspected}; +use crate::Session; +use crate::schema::tests::{assert_keys, assert_strict_keeps_todays_errors, conforms}; +use crate::schema::{ParamCheck, input_schema_for, output_schema_for}; + +/// A library file in the temporary folder, removed when dropped. +struct File(String); + +impl File { + fn new(name: &str) -> Self { + let name = format!("solidcraft-library-schema-{}-{name}.json", std::process::id()); + File(solidcraft_io::vfs::temp_dir().join(name).to_string_lossy().into_owned()) + } +} + +impl Drop for File { + fn drop(&mut self) { + let _ = std::fs::remove_file(&self.0); + } +} + +#[test] +fn schemas_and_the_key_check_agree() { + assert_keys(input_schema_for::(), &["path"]); + assert_keys(input_schema_for::(), &["format", "id", "name", "overwrite", "path", "provenance"]); + assert_keys(input_schema_for::(), &["entry", "name", "path", "revision", "targets"]); +} + +#[test] +fn strict_keeps_todays_errors() { + let file = File::new("strict"); + assert_strict_keeps_todays_errors(&[ + ("library.inspect", json!({"path": ""})), + ("library.inspect", json!({"path": file.0})), + ("library.export", json!({"path": file.0.replace(".json", ".txt")})), + ("library.export", json!({"path": file.0, "format": "solidcraft-library/3"})), + ("library.export", json!({"path": file.0, "id": "Not An Id"})), + ("library.export", json!({"path": file.0, "provenance": {"license": ""}})), + ("library.apply", json!({"path": file.0, "entry": "user.local/appearance-0", "revision": "0"})), + ("library.apply", json!({"path": file.0, "entry": "e", "revision": "0", "targets": {"faces": [{"body": "B", "point": [1e10, 0, 0]}]}})), + ]); +} + +/// #10938: exporting, reading and applying a library reply as their output schemas say, in Warn +/// without warnings; an appearance entry and a physical material entry each take their own +/// branch of the `result` schema. Like the handlers, warn and strict refuse an unknown key. +#[test] +fn library_commands_reply_with_their_schemas() { + let file = File::new("replies"); + let (inspected, exported, applied) = + (output_schema_for::(), output_schema_for::(), output_schema_for::()); + let mut s = Session { param_check: ParamCheck::Warn, ..Session::default() }; + let run = |s: &mut Session, id: &str, p: Value| s.execute(id, &p).unwrap_or_else(|e| panic!("{id} {p}: {e}")); + let matches = |schema: &schemars::Schema, r: &Value| { + let schema = schema.as_value(); + assert!(conforms(schema, schema, r), "{r} doesn't match {schema}"); + assert!(r.get("param_warnings").is_none(), "{r}"); + }; + run(&mut s, "solid.box", json!({"length": 10, "width": 10, "height": 10})); + run(&mut s, "appearance.assign", json!({"bodies": ["Body1"], "color": [180, 120, 70], "opacity": 0.8})); + run(&mut s, "material.create", json!({"name": "Timber", "density_g_cm3": 0.7, "color": "#b47846"})); + run(&mut s, "material.assign", json!({"bodies": ["Body1"], "material": "Timber"})); + let provenance = json!({"license": "CC0-1.0", "author": "A tester", "source_url": "https://example.com/library"}); + let r = run(&mut s, "library.export", json!({"path": file.0, "id": "user.test", "name": "Test", "provenance": provenance})); + matches(&exported, &r); + assert!(r["entries"].as_u64() >= Some(2), "{r}"); + let v1 = File::new("replies-v1"); + matches(&exported, &run(&mut s, "library.export", json!({"path": v1.0, "format": "solidcraft-library/1", "overwrite": true}))); + let r = run(&mut s, "library.inspect", json!({"path": file.0})); + matches(&inspected, &r); + let entries = r["catalog"]["entries"].as_array().cloned().unwrap_or_default(); + let entry = |kind: &str| { + entries + .iter() + .find(|e| e["definition"]["kind"] == kind) + .map(|e| (e["id"].clone(), e["revision"].clone())) + .unwrap_or_else(|| panic!("no {kind} in {r}")) + }; + let (look, look_revision) = entry("appearance"); + let targets = json!({"bodies": ["Body1"], "faces": [{"body": "Body1", "point": [10, 5, 5]}], "components": []}); + let r = run(&mut s, "library.apply", json!({"path": file.0, "entry": look, "revision": look_revision, "targets": targets})); + matches(&applied, &r); + assert!(r["result"]["appearance"].is_object(), "{r}"); + let (material, material_revision) = entry("material"); + let r = run( + &mut s, + "library.apply", + json!({"path": file.0, "entry": material, "revision": material_revision, "targets": {"bodies": ["Body1"]}, "name": null}), + ); + matches(&applied, &r); + assert_eq!((r["result"]["material"].as_str(), r["result"]["reused"].as_bool()), (Some("Timber"), Some(true)), "{r}"); + for level in [ParamCheck::Warn, ParamCheck::Strict] { + let mut s = Session { param_check: level, ..Session::default() }; + let error = s.execute("library.inspect", &json!({"path": file.0, "pth": 1})).err().map(|e| e.to_string()).unwrap_or_default(); + assert!(error.contains("pth"), "{level:?}: {error}"); + } +} diff --git a/crates/engine/src/schema/mod.rs b/crates/engine/src/schema/mod.rs index ab3e49cb9..8ad9d071b 100644 --- a/crates/engine/src/schema/mod.rs +++ b/crates/engine/src/schema/mod.rs @@ -63,6 +63,7 @@ pub mod features; pub mod file; pub mod inspect; pub mod joints; +pub mod libraries; pub mod mass_properties; pub mod motion; pub mod print_face; diff --git a/crates/engine/src/schema/unconverted.txt b/crates/engine/src/schema/unconverted.txt index 67f7eb3fe..c15dc2a16 100644 --- a/crates/engine/src/schema/unconverted.txt +++ b/crates/engine/src/schema/unconverted.txt @@ -113,9 +113,6 @@ joint.rigid_group joint.screw joint.solve joint.sweep -library.apply -library.export -library.inspect material.assign material.create material.delete