SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
Read design metadata and previews through a bounded seekable archive (#462)
seluneb24e478bc1d4
diff --git a/crates/io/src/design.rs b/crates/io/src/design.rsindex d5c81d7f09..a322502e90 100644--- a/crates/io/src/design.rs+++ b/crates/io/src/design.rs@@ -1,7 +1,7 @@//! Versioned design packages. Geometry is rebuilt from authoritative inputs; no-//! evaluated cache is trusted here. All archive access stays in memory, never on disk.+//! evaluated cache is trusted here. Entries are never extracted to filesystem paths.use std::collections::{BTreeMap, BTreeSet};-use std::io::{Cursor, Read, Write};+use std::io::{Cursor, Read, Seek, SeekFrom, Write};use serde_json::{Map, Value, json};use sha2::{Digest, Sha256};@@ -219,18 +219,25 @@ fn decode_mesh(bytes: &[u8], mesh: &mut MeshData) -> Result<()> {validate_mesh(mesh)}-struct PackageReader<'a> {- zip: zip::ZipArchive<Cursor<&'a [u8]>>,+struct PackageReader<R: Read + Seek> {+ zip: zip::ZipArchive<R>,blobs: BTreeMap<String, Vec<u8>>,hydrated: usize,}-impl<'a> PackageReader<'a> {- fn new(bytes: &'a [u8]) -> Result<Self> {+impl<R: Read + Seek> PackageReader<R> {+ fn new(mut source: R) -> Result<Self> {+ let length = source.seek(SeekFrom::End(0)).map_err(invalid)?;+ if length > MAX_DESIGN_BYTES as u64 {+ return Err(invalid("compressed file too large"));+ }+ let tail_length = length.min(65_557) as usize;+ source.seek(SeekFrom::Start(length - tail_length as u64)).map_err(invalid)?;+ let mut tail = vec![0; tail_length];+ source.read_exact(&mut tail).map_err(invalid)?;// zip's name index can coalesce duplicate central-directory entries. Our// bounded format does not need ZIP64/multiple disks: verify the declared// entry count as well so duplicate names cannot silently select a payload.- let tail = bytes.get(bytes.len().saturating_sub(65_557)..).ok_or_else(|| invalid("missing ZIP directory"))?;let eocd = tail.windows(4).rposition(|v| v == b"PK\x05\x06").ok_or_else(|| invalid("missing ZIP directory"))?;let end = tail.get(eocd..).filter(|v| v.len() >= 22).ok_or_else(|| invalid("truncated ZIP directory"))?;let u16_at = |offset| -> Result<u16> {@@ -241,7 +248,7 @@ impl<'a> PackageReader<'a> {if declared > MAX_ENTRIES || u16_at(4)? != 0 || u16_at(6)? != 0 || u16_at(8)? as usize != declared || end.len() != 22 + u16_at(20)? as usize {return Err(invalid("too many entries or unsupported ZIP directory"));}- let mut zip = zip::ZipArchive::new(Cursor::new(bytes)).map_err(invalid)?;+ let mut zip = zip::ZipArchive::new(source).map_err(invalid)?;if u16_at(4)? != 0|| u16_at(6)? != 0|| u16_at(8)? as usize != zip.len()@@ -342,11 +349,10 @@ pub fn read_design_preview(bytes: &[u8]) -> Option<DesignPreview> {if bytes.len() > MAX_DESIGN_BYTES || !is_design_container(bytes) {return None;}- read_preview(bytes).ok()+ DesignContainerReader::new(Cursor::new(bytes)).ok()?.preview()}-fn read_preview(bytes: &[u8]) -> Result<DesignPreview> {- let mut reader = PackageReader::new(bytes)?;+fn read_preview<R: Read + Seek>(reader: &mut PackageReader<R>) -> Result<DesignPreview> {let container: Value = serde_json::from_slice(&reader.limited_part("container.json", 4096)?).map_err(invalid)?;if !matches!(container.get("format").and_then(Value::as_str), Some(VERSION | LEGACY_VERSION)) {return Err(invalid("unsupported container version"));@@ -398,8 +404,38 @@ fn read_preview(bytes: &[u8]) -> Result<DesignPreview> {Ok(preview)}+/// A bounded container reader over an immutable, seekable source.+///+/// Opening inspects the directory, not the source blobs. `preview` reads only the+/// optional display entries and document metadata; `read_document` then resolves+/// and validates authoritative blobs. Keep the source unchanged for this reader's+/// lifetime. This type does not turn untrusted cached data into editable geometry.+pub struct DesignContainerReader<R: Read + Seek> {+ reader: PackageReader<R>,+}++impl<R: Read + Seek> DesignContainerReader<R> {+ /// Open a container (not plain JSON), enforcing the same budgets as byte IO.+ pub fn new(source: R) -> Result<Self> {+ Ok(Self { reader: PackageReader::new(source)? })+ }++ /// Optional display-only data. Corruption or incompatibility is a cache miss.+ pub fn preview(&mut self) -> Option<DesignPreview> {+ read_preview(&mut self.reader).ok()+ }++ /// Consume the reader, resolving every required blob before returning a document.+ pub fn read_document(mut self) -> Result<Document> {+ read_document(&mut self.reader)+ }+}+pub(super) fn read(bytes: &[u8]) -> Result<Document> {- let mut reader = PackageReader::new(bytes)?;+ DesignContainerReader::new(Cursor::new(bytes))?.read_document()+}++fn read_document<R: Read + Seek>(reader: &mut PackageReader<R>) -> Result<Document> {let version: Value = serde_json::from_slice(&reader.part("container.json")?).map_err(invalid)?;if !matches!(version.get("format").and_then(Value::as_str), Some(VERSION | LEGACY_VERSION)) {return Err(invalid("unsupported container version"));@@ -450,6 +486,85 @@ mod tests {use super::*;use solidcraft_geom::Vec2;+ struct CountingReader {+ source: Cursor<Vec<u8>>,+ count: std::rc::Rc<std::cell::Cell<usize>>,+ }++ impl Read for CountingReader {+ fn read(&mut self, bytes: &mut [u8]) -> std::io::Result<usize> {+ let count = self.source.read(bytes)?;+ self.count.set(self.count.get() + count);+ Ok(count)+ }+ }++ impl Seek for CountingReader {+ fn seek(&mut self, position: SeekFrom) -> std::io::Result<u64> {+ self.source.seek(position)+ }+ }++ #[test]+ fn seekable_reader_rejects_oversized_source_before_reading() {+ struct Oversized;+ impl Read for Oversized {+ fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {+ panic!("oversized input must be rejected before any allocation or read");+ }+ }+ impl Seek for Oversized {+ fn seek(&mut self, _: SeekFrom) -> std::io::Result<u64> {+ Ok(MAX_DESIGN_BYTES as u64 + 1)+ }+ }+ assert!(DesignContainerReader::new(Oversized).is_err());+ }++ #[test]+ fn seekable_preview_defers_large_source_blob_until_document_read() {+ let mut doc = Document::new("Deferred source");+ let step = "ISO-10303-21;".repeat(200_000);+ doc.add_feature(FeatureKind::Import { file: "large.step".into(), step: step.clone(), components: Vec::new() }, None).unwrap();+ let preview = DesignPreview { meshes: vec![mesh()] };+ let bytes = write_design_container_with_preview(&doc, DesignCompression::Fast, Some(&preview)).unwrap();+ let count = std::rc::Rc::new(std::cell::Cell::new(0));+ let source = CountingReader { source: Cursor::new(bytes), count: count.clone() };+ let mut reader = DesignContainerReader::new(source).unwrap();+ assert_eq!(reader.preview().unwrap().meshes[0].positions, preview.meshes[0].positions);+ // ZIP directory scans may touch a bounded suffix of a stored blob. They+ // must not load its multi-megabyte payload to obtain the saved picture.+ assert!(count.get() < 256 * 1024, "read {} bytes before display", count.get());+ let restored = reader.read_document().unwrap();+ assert_eq!(restored.to_json(), doc.to_json());+ assert!(count.get() >= step.len());+ }++ #[test]+ fn seekable_reader_validates_required_blobs_after_preview() {+ let doc = document();+ let preview = DesignPreview { meshes: vec![mesh()] };+ let mut bytes = write_design_container_with_preview(&doc, DesignCompression::Fast, Some(&preview)).unwrap();+ let marker = b"ISO-10303-21;";+ let offset = bytes.windows(marker.len()).position(|part| part == marker).unwrap();+ bytes[offset] ^= 1;+ let mut reader = DesignContainerReader::new(Cursor::new(bytes)).unwrap();+ assert!(reader.preview().is_some());+ assert!(reader.read_document().is_err());+ }++ #[test]+ fn seekable_reader_without_preview_preserves_authoritative_document() {+ let doc = document();+ let bytes = write_design_container(&doc).unwrap();+ let mut source = Cursor::new(bytes);+ source.set_position(17); // Constructor starts from the whole source, not its cursor.+ let mut reader = DesignContainerReader::new(source).unwrap();+ assert!(reader.preview().is_none());+ assert_eq!(reader.read_document().unwrap().to_json(), doc.to_json());+ assert!(DesignContainerReader::new(Cursor::new(vec![0u8; 1])).is_err());+ }+fn mesh() -> MeshData {MeshData {name: "Precise mesh".into(),@@ -676,7 +791,7 @@ mod tests {let mut entries = parts(&bytes);let mut metadata: Value = serde_json::from_slice(&entries["document.json"]).unwrap();let reference = metadata["features"][0].clone();- let mut reader = PackageReader::new(&bytes).unwrap();+ let mut reader = PackageReader::new(Cursor::new(&bytes)).unwrap();reader.hydrated = MAX_EXPANDED;assert!(reader.blob(&reference, "step_blob", "step").unwrap_err().to_string().contains("resolved payloads too large"));for name in ["../escape.step", "blobs/not-a-hash.step", "blobs/00.png"] {@@ -696,6 +811,10 @@ mod tests {std::panic::catch_unwind(|| {let _ = crate::read_design(&bytes[..end]);let _ = read_design_preview(&bytes[..end]);+ if let Ok(mut reader) = DesignContainerReader::new(Cursor::new(&bytes[..end])) {+ let _ = reader.preview();+ let _ = reader.read_document();+ }}).is_ok(),"truncated at {end}"@@ -713,6 +832,10 @@ mod tests {std::panic::catch_unwind(|| {let _ = crate::read_design(&changed);let _ = read_design_preview(&changed);+ if let Ok(mut reader) = DesignContainerReader::new(Cursor::new(&changed)) {+ let _ = reader.preview();+ let _ = reader.read_document();+ }}).is_ok());diff --git a/crates/io/src/lib.rs b/crates/io/src/lib.rsindex bfca84251c..c75753dbe7 100644--- a/crates/io/src/lib.rs+++ b/crates/io/src/lib.rs@@ -10,8 +10,8 @@ mod design;mod design_metadata;mod dxf;pub use design::{- DesignCompression, DesignPreview, is_design_container, read_design_preview, write_design_container, write_design_container_with_compression,- write_design_container_with_preview,+ DesignCompression, DesignContainerReader, DesignPreview, is_design_container, read_design_preview, write_design_container,+ write_design_container_with_compression, write_design_container_with_preview,};mod legacy_dir;pub mod safe_write;diff --git a/docs/design-container.md b/docs/design-container.mdindex 0c7d417797..8b7e26f34d 100644--- a/docs/design-container.md+++ b/docs/design-container.md@@ -89,3 +89,62 @@ any change of active document/revision discards both preview and completion.Normal design reading, CLI and browser opening still rebuild authoritatively; noevaluated B-rep is deserialized or adopted. Portable evaluated B-rep/state restorationand interactive cached viewport navigation remain further work in #303.++## Seekable reader (phase 2, first increment)++`io::DesignContainerReader<R: Read + Seek>` accepts a container source such as a+file or a memory cursor. It inspects a bounded ZIP directory suffix and entry+headers, then `preview()` reads the optional display entries and document metadata.+`read_document()` consumes the reader and resolves and validates the required+source blobs through the same archive. No complete archive buffer is required.+The existing byte-based readers use this implementation too; JSON keeps its existing+reader. This increment provides the IO API; desktop and browser integration remain+separate. It does not yet change application opening times or saving behavior.++The source must remain unchanged for the lifetime of the reader. A file handle is+not an immutable snapshot of concurrent in-place writes: application integration+must address that before publishing a cached view. Optional preview success never+validates source blobs or makes a document editable. An invalid required blob still+fails the later document read. ZIP directory scans can touch a bounded suffix of a+stored blob; deferral means not loading or decoding the complete payload, not zero+physical reads of its byte range. Metadata retains the existing part-size budget.++A counting-reader regression uses a 2.6 MB stored source blob and obtains the saved+preview with fewer than 256 KiB read, then verifies the authoritative document is+identical after resolving its source. Corrupt-source and preview-miss regressions,+and truncation/seeded mutations through the combined reader, protect the boundary.+This is an IO-volume test, not a geometry or first-frame benchmark.++## Remaining #303 increments and kernel independence++Keep each increment independently reviewable after the phase-one container PR:++1. Seekable IO and its read-volume/hostile-input tests (the API above).+2. A versioned SolidCraft-owned B-rep schema and bounded binary codec, tested without+ constructing a kernel body. Topology references, oriented edge uses and face+ loops, geometric domains, analytic/spline curve and surface definitions, units,+ tolerances and orientation must have explicit semantics. Preserve face-source+ certificates, persistent names and history using SolidCraft-owned identities.+ No truck serialized structs, memory layouts, pointers or opaque kernel blobs+ form part of the persisted contract. No evaluated STEP round trip is a substitute.+3. Separate adapters between the neutral schema and supported kernels. Unsupported+ geometry or provenance is a cache miss, never a lossy approximation. A neutral+ file schema alone does not prove interoperability: each adapter needs round-trip,+ modelling and naming tests; compatibility with a second kernel is unverified+ until that adapter exists. Kernel/version information belongs in producer and+ capability metadata, not in the topology encoding. Conservative cache invalidation+ is allowed across kernels while authoritative document reopening still works.+4. Integrate deferred source reading and provisional B-rep display into the open+ worker with immutable-input and document/revision guards. Rebuild authoritatively+ before editing, picking or measuring. B-rep alone is not a complete evaluated+ session: sketches, construction, placements and other non-solid state still matter.+5. Measure cold first display, time until editing, save latency, size and peak memory+ on a public STEP-based design. Include cache hits/misses, plain JSON and browser+ fallback, and report baselines and limitations in `docs/perf.md`.++Default saving must remain fast: do not force cold evaluation or meshing merely to+produce a disposable cache. Do not add redundant display meshes by default; the+existing preview remains opt-in. GPU tessellation is independent work. Continue+using format/application constants rather than source-tree hashing build scripts,+retain JSON Save As/MCP/script compatibility and the documented legacy shims, and+run standalone wasm validation on each published code revision.