Share bounded portable material archives

This commit is contained in:
Dylan M. Taylor committed 2026-11-15 11:26:24 +00:00
1 parent 5a0caf286e
commit 7dbfafa356
5 files changed
+236

No files matched your search

Generated
+10
View File
@@ -2056,6 +2056,16 @@ dependencies = [
"serde_json",
]
[[package]]
name = "craft-mcmat"
version = "0.1.0"
dependencies = [
"craft-zip",
"serde",
"serde_json",
"thiserror 2.0.21",
]
[[package]]
name = "craft-media"
version = "0.1.0"
+1
View File
@@ -51,6 +51,7 @@ craft-dialogs = { path = "crates/dialogs" }
craft-doc-binary = { path = "crates/doc-binary" }
craft-docx = { path = "crates/docx" }
craft-document-bundle = { path = "crates/document-bundle" }
craft-mcmat = { path = "crates/mcmat" }
craft-designcraft-format = { path = "crates/designcraft-format" }
craft-dxf = { path = "crates/dxf" }
craft-drawingml = { path = "crates/drawingml" }
+17
View File
@@ -0,0 +1,17 @@
[package]
name = "craft-mcmat"
description = "Bounded portable material archive interchange for Craft applications"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
craft-zip = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
+17
View File
@@ -0,0 +1,17 @@
# craft-mcmat
A bounded reader and writer for portable MaterialCraft `.mcmat` ZIP packages. A package
contains `material.json`, named texture maps and a source package. Applications interpret
parameter values and cook or render maps themselves; this crate does not depend on an app's
model. It supports callers that read either version 1 or version 2 of the manifest, or both.
`Material::open` takes caller-provided version, entry-count, map-count, per-entry and total
expanded-byte limits. Each subsequent `read` and `read_source` shares that budget, including
repeated references to the same ZIP member. Duplicate member names are refused. The manifest
preserves unknown fields at the top level and on maps; parameter, input and preset objects are
kept as JSON values so their unknown fields survive too. `write` preserves the caller's source
entry name and map names, and rejects duplicate archive member names through `craft-zip`.
The source package is opaque. Version 1 commonly names `source.mcraft`; MaterialCraft's version 2
writer names `source.sbs`. Callers that invoke another application must preserve the source's
format and extension rather than infer it from `.mcmat` alone.
+191
View File
@@ -0,0 +1,191 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
//! Bounded interchange for MaterialCraft portable materials (`.mcmat`).
//!
//! The manifest and its version belong to the format, while interpreting parameter values,
//! cooking maps and opening the source package belong to the caller. Unknown fields survive
//! deserialization and serialization, including fields added by later versions.
use std::collections::BTreeMap;
use craft_zip::{Archive, Compression, Writer};
use serde::{Deserialize, Serialize};
use serde_json::Value;
pub const FORMAT: &str = "craft-material";
pub const MANIFEST_ENTRY: &str = "material.json";
/// A portable manifest; typed parameter values remain JSON so applications can adapt their own model.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Manifest {
pub format: String,
pub version: u32,
pub name: String,
pub graph: String,
pub size: [u32; 2],
pub maps: Vec<MapEntry>,
#[serde(default)]
pub parameters: Vec<Value>,
#[serde(default)]
pub inputs: Vec<Value>,
#[serde(default)]
pub presets: Vec<Value>,
pub source: String,
#[serde(flatten)]
pub extra: BTreeMap<String, Value>,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MapEntry {
pub usage: String,
pub file: String,
#[serde(flatten)]
pub extra: BTreeMap<String, Value>,
}
/// All limits are supplied by the consumer, including the versions it understands.
#[derive(Clone, Copy, Debug)]
pub struct Limits {
pub min_version: u32,
pub max_version: u32,
pub max_entries: u64,
pub max_maps: usize,
pub max_manifest_bytes: u64,
pub max_entry_bytes: u64,
pub max_total_bytes: u64,
}
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("invalid portable material: {0}")]
Invalid(String),
#[error("unsupported portable material version {0}")]
Version(u32),
#[error("portable material limit: {0}")]
Limit(String),
#[error("portable material archive: {0}")]
Archive(#[from] craft_zip::Error),
}
/// Manifest and original archive, retaining one shared expanded-byte budget across reads.
pub struct Material<'a> {
pub manifest: Manifest,
archive: Archive<'a>,
max_entry_bytes: u64,
}
impl<'a> Material<'a> {
pub fn open(bytes: &'a [u8], limits: Limits) -> Result<Self, Error> {
let mut archive = Archive::open(bytes, craft_zip::Limits { max_entries: limits.max_entries, max_total_bytes: limits.max_total_bytes })?;
if archive.has_duplicate_names() {
return Err(Error::Invalid("duplicate archive entries".into()));
}
let json = archive.read(MANIFEST_ENTRY, limits.max_manifest_bytes)?.ok_or_else(|| Error::Invalid("material.json is missing".into()))?;
let manifest: Manifest = serde_json::from_slice(&json).map_err(|e| Error::Invalid(format!("material.json: {e}")))?;
if manifest.format != FORMAT {
return Err(Error::Invalid(format!("format `{}`", manifest.format)));
}
if !(limits.min_version..=limits.max_version).contains(&manifest.version) {
return Err(Error::Version(manifest.version));
}
if manifest.maps.len() > limits.max_maps {
return Err(Error::Limit(format!("{} maps exceeds {}", manifest.maps.len(), limits.max_maps)));
}
Ok(Self { manifest, archive, max_entry_bytes: limits.max_entry_bytes })
}
/// Read one named member, charging it to the same budget as previous reads.
pub fn read(&mut self, name: &str) -> Result<Vec<u8>, Error> {
self.archive.read(name, self.max_entry_bytes)?.ok_or_else(|| Error::Invalid(format!("{name} is missing")))
}
pub fn read_source(&mut self) -> Result<Vec<u8>, Error> {
self.read(&self.manifest.source.clone())
}
}
/// Write a manifest, its named maps, and the source. Duplicate member names are rejected.
pub fn write(manifest: &Manifest, maps: &[(String, Vec<u8>)], source: &[u8]) -> Result<Vec<u8>, Error> {
let json = serde_json::to_vec_pretty(manifest).map_err(|e| Error::Invalid(format!("material.json: {e}")))?;
let mut writer = Writer::new();
writer.add(MANIFEST_ENTRY, &json, Compression::Deflated)?;
for (name, bytes) in maps {
writer.add(name, bytes, Compression::Stored)?;
}
writer.add(&manifest.source, source, Compression::Stored)?;
Ok(writer.finish()?)
}
#[cfg(test)]
mod tests {
use super::*;
fn limits() -> Limits {
Limits {
min_version: 1,
max_version: 2,
max_entries: 100,
max_maps: 4,
max_manifest_bytes: 4096,
max_entry_bytes: 100,
max_total_bytes: 8192,
}
}
fn sample(version: u32) -> Manifest {
serde_json::from_value(serde_json::json!({
"format": "craft-material", "version": version, "name": "Stone", "graph": "Stone", "size": [64, 64],
"maps": [{"usage": "baseColor", "file": "maps/base.png", "colorSpace": "srgb", "futureMap": true}],
"parameters": [{"id": "rough", "value": {"t": "float", "v": 0.25}, "futureParam": 42}],
"inputs": [{"identifier": "curvature", "kind": "gray"}], "presets": [],
"source": if version == 1 { "source.mcraft" } else { "source.sbs" }, "futureField": {"keep": true}
}))
.unwrap()
}
#[test]
fn both_protocol_versions_keep_unknown_fields_and_payloads() {
for version in [1, 2] {
let manifest = sample(version);
let bytes = write(&manifest, &[("maps/base.png".into(), vec![1, 2, 3])], b"source").unwrap();
let mut material = Material::open(&bytes, limits()).unwrap();
assert_eq!(material.manifest, manifest);
assert_eq!(material.read("maps/base.png").unwrap(), [1, 2, 3]);
assert_eq!(material.read_source().unwrap(), b"source");
let json = serde_json::to_value(&material.manifest).unwrap();
assert_eq!(json["futureField"]["keep"], true);
assert_eq!(json["maps"][0]["futureMap"], true);
assert_eq!(json["parameters"][0]["futureParam"], 42);
}
}
#[test]
fn limits_apply_to_the_manifest_maps_and_aggregate_reads() {
let manifest = sample(2);
let bytes = write(&manifest, &[("maps/base.png".into(), vec![1; 8])], &[2; 8]).unwrap();
let mut unsupported = limits();
unsupported.max_version = 1;
assert!(matches!(Material::open(&bytes, unsupported), Err(Error::Version(2))));
let mut no_maps = limits();
no_maps.max_maps = 0;
assert!(matches!(Material::open(&bytes, no_maps), Err(Error::Limit(_))));
let mut tiny_entry = limits();
tiny_entry.max_entry_bytes = 7;
assert!(Material::open(&bytes, tiny_entry).unwrap().read("maps/base.png").is_err());
let json_len = serde_json::to_vec_pretty(&manifest).unwrap().len() as u64;
let mut aggregate = limits();
aggregate.max_total_bytes = json_len + 15;
let mut material = Material::open(&bytes, aggregate).unwrap();
assert_eq!(material.read("maps/base.png").unwrap().len(), 8);
assert!(material.read_source().is_err());
}
#[test]
fn refuses_duplicate_names_on_write() {
let manifest = sample(2);
let duplicate = [("maps/base.png".to_string(), vec![1]), ("maps/base.png".to_string(), vec![2])];
assert!(write(&manifest, &duplicate, b"source").is_err());
}
}