Publish MCMAT v3 as a bounded procedural source archive

This commit is contained in:
chasse20 committed 2026-11-18 01:54:53 -05:00
1 parent af1a6b4261
commit 5ae0786c5b
2 files changed
+133 -171

No files matched your search

+7 -14
View File
@@ -1,17 +1,10 @@
# 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.
The MCMAT v3 portable material is a ZIP containing a version-only `material.json`, one
`source.sbs`, and the required source assets under `resources/`. The sole root-level
material graph in the SBS is the entry. Applications inspect its exposed controls and
cook its outputs through MaterialCraft. Texture maps and MaterialX documents are generated
by exporters. Earlier archives must be republished from their original projects.
`is_material` checks for a manifest with a bounded ZIP index; `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.
`Material::open` checks archive entries and expansion budgets before returning source
files. `write` compresses the XML and version marker and preserves source asset bytes.
+126 -157
View File
@@ -1,133 +1,126 @@
#![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;
//! The clean-room MCMAT v3 source archive. Applications interpret the SBS entry graph.
use craft_zip::{Archive, Compression, Writer};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use serde::Deserialize;
use std::collections::{BTreeMap, BTreeSet};
pub const FORMAT: &str = "craft-material";
pub const VERSION: u32 = 3;
pub const MANIFEST_ENTRY: &str = "material.json";
pub const SOURCE_ENTRY: &str = "source.sbs";
const MARKER: &[u8] = br#"{"version":3}"#;
/// 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,
}
impl Default for Limits {
fn default() -> Self {
Self { max_entries: 100_000, max_manifest_bytes: 64 << 20, max_entry_bytes: 256 << 20, max_total_bytes: 1 << 30 }
}
}
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("invalid portable material: {0}")]
Invalid(String),
#[error("unsupported portable material version {0}")]
#[error("unsupported .mcmat version {0} (expected 3). Republish from the original authoring project")]
Version(u32),
#[error("portable material limit: {0}")]
Limit(String),
#[error("portable material archive: {0}")]
Archive(#[from] craft_zip::Error),
}
/// Whether a bounded ZIP index contains a material manifest. This does not validate the manifest.
/// File sniffing also recognizes old manifests so the reader can give republishing guidance.
pub fn is_material(bytes: &[u8], max_entries: u64) -> bool {
Archive::open(bytes, craft_zip::Limits { max_entries, max_total_bytes: 0 })
.is_ok_and(|archive| !archive.has_duplicate_names() && archive.contains(MANIFEST_ENTRY))
Archive::open(bytes, craft_zip::Limits { max_entries, max_total_bytes: 0 }).is_ok_and(|archive| archive.contains(MANIFEST_ENTRY))
}
/// 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,
fn valid_resource(name: &str) -> bool {
name.len() <= 4096
&& name.starts_with("resources/")
&& !name.contains(['\\', ':'])
&& !name.chars().any(char::is_control)
&& name.split('/').all(|part| !matches!(part, "" | "." | ".."))
}
impl<'a> Material<'a> {
pub fn open(bytes: &'a [u8], limits: Limits) -> Result<Self, Error> {
#[derive(Debug)]
pub struct Material {
pub source: Vec<u8>,
/// Keys are paths relative to source.sbs, including the resources/ prefix.
pub resources: BTreeMap<String, Vec<u8>>,
}
impl Material {
pub fn open(bytes: &[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()));
if archive.has_duplicate_names() || archive.has_overlapping_files()? {
return Err(Error::Invalid("duplicate or overlapping 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)));
let json = archive.read(MANIFEST_ENTRY, limits.max_manifest_bytes)?.ok_or_else(|| Error::Invalid("missing material.json".into()))?;
#[derive(Deserialize)]
struct Version {
version: u32,
}
if !(limits.min_version..=limits.max_version).contains(&manifest.version) {
return Err(Error::Version(manifest.version));
let marker: Version = serde_json::from_slice(&json).map_err(|err| Error::Invalid(format!("material.json: {err}")))?;
if marker.version != VERSION {
return Err(Error::Version(marker.version));
}
if manifest.maps.len() > limits.max_maps {
return Err(Error::Limit(format!("{} maps exceeds {}", manifest.maps.len(), limits.max_maps)));
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Marker {
version: u32,
}
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())
if !serde_json::from_slice::<Marker>(&json).is_ok_and(|m| m.version == VERSION) {
return Err(Error::Invalid("material.json must contain only the version".into()));
}
let source = archive.read(SOURCE_ENTRY, limits.max_entry_bytes)?.ok_or_else(|| Error::Invalid("missing source.sbs".into()))?;
let mut resources = BTreeMap::new();
let mut seen = BTreeSet::new();
for index in 0..archive.len() {
let name = archive.entry_name(index)?.ok_or_else(|| Error::Invalid("invalid entry name".into()))?;
if name == SOURCE_ENTRY || name == MANIFEST_ENTRY {
continue;
}
if name.strip_suffix('/').is_some_and(|dir| dir == "resources" || valid_resource(dir)) {
continue;
}
if !valid_resource(&name) || !seen.insert(name.to_ascii_lowercase()) {
return Err(Error::Invalid(format!("invalid or ambiguous resource path `{name}`")));
}
let data = archive.read(&name, limits.max_entry_bytes)?.ok_or_else(|| Error::Invalid(format!("missing `{name}`")))?;
resources.insert(name, data);
}
Ok(Self { source, resources })
}
}
/// 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> {
// Flattened fields must not serialize a second copy of a known key.
const KNOWN: &[&str] = &["format", "version", "name", "graph", "size", "maps", "parameters", "inputs", "presets", "source"];
if manifest.extra.keys().any(|key| KNOWN.contains(&key.as_str()))
|| manifest.maps.iter().any(|map| map.extra.contains_key("usage") || map.extra.contains_key("file"))
{
return Err(Error::Invalid("an extra field duplicates a known field".into()));
}
let json = serde_json::to_vec_pretty(manifest).map_err(|e| Error::Invalid(format!("material.json: {e}")))?;
/// Write one SBS document with its referenced source assets.
pub fn write<'a>(source: &[u8], resources: impl IntoIterator<Item = (&'a str, &'a [u8])>) -> Result<Vec<u8>, Error> {
let limits = Limits::default();
let mut writer = Writer::new();
writer.add(MANIFEST_ENTRY, &json, Compression::Deflated)?;
for (name, bytes) in maps {
writer.add(name, bytes, Compression::Stored)?;
let mut seen = BTreeSet::new();
let mut total = (source.len() as u64).saturating_add(MARKER.len() as u64);
if source.len() as u64 > limits.max_entry_bytes {
return Err(Error::Invalid("source.sbs exceeds the entry limit".into()));
}
writer.add(MANIFEST_ENTRY, MARKER, Compression::Deflated)?;
writer.add(SOURCE_ENTRY, source, Compression::Deflated)?;
for (name, bytes) in resources {
if !valid_resource(name) || !seen.insert(name.to_ascii_lowercase()) {
return Err(Error::Invalid(format!("invalid or ambiguous resource path `{name}`")));
}
total = total.saturating_add(bytes.len() as u64);
if bytes.len() as u64 > limits.max_entry_bytes || total > limits.max_total_bytes || seen.len() as u64 + 2 > limits.max_entries {
return Err(Error::Invalid(format!("archive limits exceeded at `{name}`")));
}
let compression = if name.ends_with(".svg") { Compression::Deflated } else { Compression::Stored };
writer.add(name, bytes, compression)?;
}
writer.add(&manifest.source, source, Compression::Stored)?;
Ok(writer.finish()?)
}
@@ -135,82 +128,58 @@ pub fn write(manifest: &Manifest, maps: &[(String, Vec<u8>)], source: &[u8]) ->
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();
assert!(is_material(&bytes, 100));
assert!(!is_material(&bytes, 1));
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);
fn procedural_source_and_assets_round_trip_under_one_budget() {
let bytes = write(b"<package/>", [("resources/oak.png", b"image".as_slice())]).unwrap();
let pkg = Material::open(&bytes, Limits::default()).unwrap();
assert_eq!(pkg.source, b"<package/>");
assert_eq!(pkg.resources["resources/oak.png"], b"image");
let mut archive = Archive::open(&bytes, craft_zip::Limits { max_entries: 3, max_total_bytes: 128 }).unwrap();
assert_eq!(archive.read(MANIFEST_ENTRY, 32).unwrap().unwrap(), MARKER);
assert_eq!(archive.is_stored(SOURCE_ENTRY), Some(false));
assert_eq!(archive.is_stored("resources/oak.png"), Some(true));
for limits in [
Limits { max_entries: 2, ..Default::default() },
Limits { max_entry_bytes: 2, ..Default::default() },
Limits { max_total_bytes: 24, ..Default::default() },
] {
assert!(Material::open(&bytes, limits).is_err());
}
}
#[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());
fn rejects_previous_versions_before_requiring_the_v3_layout() {
for version in [0, 1, 2, 4] {
let mut zip = Writer::new();
zip.add(MANIFEST_ENTRY, format!(r#"{{"format":"craft-material","version":{version}}}"#).as_bytes(), Compression::Deflated).unwrap();
let bytes = zip.finish().unwrap();
assert!(is_material(&bytes, 2));
assert!(matches!(Material::open(&bytes, Limits::default()), Err(Error::Version(v)) if v == version));
}
}
#[test]
fn refuses_extra_fields_that_duplicate_known_keys() {
let mut manifest = sample(2);
manifest.extra.insert("version".into(), 3.into());
assert!(write(&manifest, &[], b"source").is_err());
manifest.extra.remove("version");
manifest.maps[0].extra.insert("file".into(), "other".into());
assert!(write(&manifest, &[], b"source").is_err());
fn v3_requires_source_and_a_version_only_marker() {
for (marker, source) in [(MARKER, None), (br#"{"version":3,"graph":"Other"}"#.as_slice(), Some(b"<package/>".as_slice()))] {
let mut zip = Writer::new();
zip.add(MANIFEST_ENTRY, marker, Compression::Deflated).unwrap();
if let Some(source) = source {
zip.add(SOURCE_ENTRY, source, Compression::Deflated).unwrap();
}
assert!(Material::open(&zip.finish().unwrap(), Limits::default()).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());
fn rejects_ambiguous_or_nonlocal_resource_members() {
for name in ["resources/../../x", "resources/a\\x", "/x", "maps/color.png", "resources/C:/x", "preview.png"] {
assert!(write(b"x", [(name, &b"x"[..])]).is_err());
let mut zip = Writer::new();
zip.add(MANIFEST_ENTRY, MARKER, Compression::Stored).unwrap();
zip.add(SOURCE_ENTRY, b"x", Compression::Deflated).unwrap();
zip.add(name, b"x", Compression::Stored).unwrap();
assert!(Material::open(&zip.finish().unwrap(), Limits::default()).is_err());
}
assert!(write(b"x", [("resources/A", &b"a"[..]), ("resources/a", &b"b"[..])]).is_err());
}
}