From e66b3a79549bc951f9ebbd2783c2972401de72d7 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Mon, 16 Nov 2026 23:23:25 -0500 Subject: [PATCH] zip: support bounded aligned stored entry options Co-authored-by: bflatastic --- ATTRIBUTION.md | 4 +++ crates/zip/src/write.rs | 21 ++++++++++++- crates/zip/tests/aligned_writer.rs | 49 ++++++++++++++++++++++++++++++ 3 files changed, 73 insertions(+), 1 deletion(-) create mode 100644 crates/zip/tests/aligned_writer.rs diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 9d260300c..d676c47c0 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -114,3 +114,7 @@ The XML reader in `crates/plist/src/xml.rs` and its base64 compatibility helper ## GIMP palette reader `crates/palette` extracts the GPL text parser from AniCraft `crates/doc/src/swatch.rs` at `d875a7feb250e6ab06aa28a37fb78a0699e88330` (MIT OR Apache-2.0), introduced by Tanish Manku in `a64130a9da9bdde545463b852d95d6a6774b1dfd` (AniCraft #270). The import preserves Tanish as primary author. Neutral RGB/name adaptation separates application display-name sanitization and the `Untitled` policy; validation tests and integration are subsequent Dylan M. Taylor changes. + +## Aligned stored ZIP entries + +The USDZ alignment requirement and compatibility fixture for `Writer::add_stored_aligned` come from TextureCraft `crates/formats/src/mesh_export/usd.rs`, introduced by bflatastic in `bdbb52c9` and maintained through `9eb20086` (MIT OR Apache-2.0). The shared API and alignment validation are subsequent Dylan M. Taylor work. Scene/material mapping remains in TextureCraft. diff --git a/crates/zip/src/write.rs b/crates/zip/src/write.rs index e1fdfad9e..6e62c6f20 100644 --- a/crates/zip/src/write.rs +++ b/crates/zip/src/write.rs @@ -44,6 +44,24 @@ impl Writer { /// Adds an entry from a byte slice. A name the archive already has is an error. pub fn add(&mut self, name: &str, data: &[u8], compression: Compression) -> Result<(), Error> { + self.add_entry(name, data, compression, 1) + } + + /// Adds a stored entry whose payload starts on an `alignment`-byte boundary. + /// + /// USDZ uses 64. Only powers of two from 1 through 4096 are accepted, bounding + /// per-entry padding. This does not impose a total archive-size budget; callers + /// retain their format-specific size and name policies. Discard the writer after + /// a write error, just as for [`Self::add`]. Invalid alignment is rejected before + /// starting an entry. + pub fn add_stored_aligned(&mut self, name: &str, data: &[u8], alignment: u16) -> Result<(), Error> { + if !alignment.is_power_of_two() || alignment > 4096 { + return Err(Error::Write("alignment must be a power of two between 1 and 4096".into())); + } + self.add_entry(name, data, Compression::Stored, alignment) + } + + fn add_entry(&mut self, name: &str, data: &[u8], compression: Compression, alignment: u16) -> Result<(), Error> { let (method, level) = match compression { Compression::Stored => (zip::CompressionMethod::Stored, None), Compression::Deflated => (zip::CompressionMethod::Deflated, Some(6)), @@ -53,7 +71,8 @@ impl Writer { .compression_method(method) .compression_level(level) .last_modified_time(zip::DateTime::default()) - .large_file(data.len() as u64 >= u64::from(u32::MAX) / 2); + .large_file(data.len() as u64 >= u64::from(u32::MAX) / 2) + .with_alignment(alignment); let fail = |e: &dyn std::fmt::Display| Error::Write(format!("{name}: {e}")); self.zip.start_file(name, options).map_err(|e| fail(&e))?; self.zip.write_all(data).map_err(|e| fail(&e)) diff --git a/crates/zip/tests/aligned_writer.rs b/crates/zip/tests/aligned_writer.rs new file mode 100644 index 000000000..03c664e5b --- /dev/null +++ b/crates/zip/tests/aligned_writer.rs @@ -0,0 +1,49 @@ +use craft_zip::{Compression, Writer}; +use std::io::{Cursor, Read, Write}; + +#[test] +fn aligned_stored_matches_previous_usdz_writer() { + for tail in 0..128 { + let payload = vec![37u8; tail]; + let entries: [(&str, &[u8]); 3] = [("scene.usdc", b"PXR-USDC"), ("textures/synthetic.png", &payload), ("empty", b"")]; + let mut shared = Writer::new(); + let mut previous = zip::ZipWriter::new(Cursor::new(Vec::new())); + let options = zip::write::SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored).with_alignment(64); + for (name, data) in entries { + shared.add_stored_aligned(name, data, 64).unwrap(); + previous.start_file(name, options).unwrap(); + previous.write_all(data).unwrap(); + } + let bytes = shared.finish().unwrap(); + assert_eq!(bytes, previous.finish().unwrap().into_inner()); + let mut archive = zip::ZipArchive::new(Cursor::new(&bytes)).unwrap(); + for (i, (name, expected)) in entries.iter().enumerate() { + let mut file = archive.by_index(i).unwrap(); + assert_eq!(file.name().unwrap(), *name); + assert_eq!(file.compression(), zip::CompressionMethod::Stored); + assert_eq!(file.data_start().unwrap() % 64, 0); + let mut actual = Vec::new(); + file.read_to_end(&mut actual).unwrap(); + assert_eq!(actual, *expected); + } + } +} + +#[test] +fn invalid_alignment_does_not_start_entry_and_duplicates_fail() { + let mut writer = Writer::new(); + for alignment in [0, 3, 65, 8192, u16::MAX] { + assert!(writer.add_stored_aligned("layer", b"data", alignment).is_err()); + } + writer.add_stored_aligned("layer", b"data", 64).unwrap(); + assert!(writer.add_stored_aligned("layer", b"again", 64).is_err()); +} + +#[test] +fn alignment_one_retains_ordinary_stored_bytes() { + let mut ordinary = Writer::new(); + ordinary.add("entry", b"data", Compression::Stored).unwrap(); + let mut aligned = Writer::new(); + aligned.add_stored_aligned("entry", b"data", 1).unwrap(); + assert_eq!(ordinary.finish().unwrap(), aligned.finish().unwrap()); +}