// SPDX-License-Identifier: Prosperity-3.0.0 // Copyright Scienting // Source: https://git.scient.ing/education/coursebank //! A minimal ZIP writer, stored (uncompressed) entries only. //! //! Canvas needs a `.zip` to import a QTI package, and that is the only reason //! this crate needs ZIP at all. Writing ~120 lines of well-understood format //! beats taking a dependency whose API has changed shape several times, and it //! buys two things worth having: the archives are byte-for-byte reproducible, //! because the timestamp is fixed rather than read from the clock, and a QTI //! package diffs cleanly in a course repository. //! //! Entries are stored rather than deflated. A quiz package is a few tens of //! kilobytes of XML, so compression saves nothing that matters, and the //! Gradescope and Canvas exports in the wild are stored too. use std::io::Write; use std::path::Path; use crate::error::{Error, Result}; /// CRC-32 (IEEE 802.3) of a byte slice. /// /// # Arguments /// /// * `data` - the bytes to checksum. /// /// # Returns /// /// The checksum. fn crc32(data: &[u8]) -> u32 { let mut table = [0u32; 256]; for (i, entry) in table.iter_mut().enumerate() { let mut c = i as u32; for _ in 0..8 { c = if c & 1 != 0 { 0xEDB8_8320 ^ (c >> 1) } else { c >> 1 }; } *entry = c; } let mut crc = 0xFFFF_FFFFu32; for b in data { crc = table[((crc ^ *b as u32) & 0xFF) as usize] ^ (crc >> 8); } crc ^ 0xFFFF_FFFF } /// One file to place in the archive. struct Entry { /// The path inside the archive, always with forward slashes. name: String, /// The file contents. data: Vec, /// CRC-32 of `data`. crc: u32, /// Byte offset of this entry's local header. offset: u32, } /// Builds a ZIP archive in memory. #[derive(Default)] pub struct ZipBuilder { entries: Vec, body: Vec, } /// The fixed DOS timestamp used for every entry: 1980-01-01 00:00:00. /// /// A real clock value would make otherwise identical packages differ, which /// defeats the point of committing them. const DOS_TIME: u16 = 0; /// The DOS date for 1980-01-01. const DOS_DATE: u16 = 0x0021; impl ZipBuilder { /// Creates an empty archive. pub fn new() -> ZipBuilder { ZipBuilder::default() } /// Adds a file to the archive. /// /// # Arguments /// /// * `name` - the path inside the archive. /// * `data` - the contents. pub fn add(&mut self, name: &str, data: impl Into>) { let data = data.into(); let crc = crc32(&data); let offset = self.body.len() as u32; let name = name.replace('\\', "/"); let name_bytes = name.as_bytes(); // Local file header. self.body.extend_from_slice(&0x0403_4b50u32.to_le_bytes()); self.body.extend_from_slice(&20u16.to_le_bytes()); // version needed self.body.extend_from_slice(&0u16.to_le_bytes()); // flags self.body.extend_from_slice(&0u16.to_le_bytes()); // method: stored self.body.extend_from_slice(&DOS_TIME.to_le_bytes()); self.body.extend_from_slice(&DOS_DATE.to_le_bytes()); self.body.extend_from_slice(&crc.to_le_bytes()); self.body .extend_from_slice(&(data.len() as u32).to_le_bytes()); self.body .extend_from_slice(&(data.len() as u32).to_le_bytes()); self.body .extend_from_slice(&(name_bytes.len() as u16).to_le_bytes()); self.body.extend_from_slice(&0u16.to_le_bytes()); // extra field length self.body.extend_from_slice(name_bytes); self.body.extend_from_slice(&data); self.entries.push(Entry { name, data, crc, offset, }); } /// Adds a text file to the archive. /// /// # Arguments /// /// * `name` - the path inside the archive. /// * `text` - the contents. pub fn add_text(&mut self, name: &str, text: &str) { self.add(name, text.as_bytes().to_vec()); } /// Serializes the archive. /// /// # Returns /// /// The complete ZIP file bytes. pub fn finish(self) -> Vec { let mut out = self.body; let cd_offset = out.len() as u32; for e in &self.entries { let name = e.name.as_bytes(); out.extend_from_slice(&0x0201_4b50u32.to_le_bytes()); out.extend_from_slice(&20u16.to_le_bytes()); // version made by out.extend_from_slice(&20u16.to_le_bytes()); // version needed out.extend_from_slice(&0u16.to_le_bytes()); // flags out.extend_from_slice(&0u16.to_le_bytes()); // method: stored out.extend_from_slice(&DOS_TIME.to_le_bytes()); out.extend_from_slice(&DOS_DATE.to_le_bytes()); out.extend_from_slice(&e.crc.to_le_bytes()); out.extend_from_slice(&(e.data.len() as u32).to_le_bytes()); out.extend_from_slice(&(e.data.len() as u32).to_le_bytes()); out.extend_from_slice(&(name.len() as u16).to_le_bytes()); out.extend_from_slice(&0u16.to_le_bytes()); // extra out.extend_from_slice(&0u16.to_le_bytes()); // comment out.extend_from_slice(&0u16.to_le_bytes()); // disk number out.extend_from_slice(&0u16.to_le_bytes()); // internal attrs out.extend_from_slice(&0u32.to_le_bytes()); // external attrs out.extend_from_slice(&e.offset.to_le_bytes()); out.extend_from_slice(name); } let cd_size = out.len() as u32 - cd_offset; // End of central directory. out.extend_from_slice(&0x0605_4b50u32.to_le_bytes()); out.extend_from_slice(&0u16.to_le_bytes()); // this disk out.extend_from_slice(&0u16.to_le_bytes()); // disk with cd out.extend_from_slice(&(self.entries.len() as u16).to_le_bytes()); out.extend_from_slice(&(self.entries.len() as u16).to_le_bytes()); out.extend_from_slice(&cd_size.to_le_bytes()); out.extend_from_slice(&cd_offset.to_le_bytes()); out.extend_from_slice(&0u16.to_le_bytes()); // comment length out } /// Writes the archive to a file. /// /// # Arguments /// /// * `path` - the destination. /// /// # Errors /// /// Returns [`Error::Io`] on a write failure. pub fn write_to(self, path: &Path) -> Result<()> { if let Some(parent) = path.parent() { std::fs::create_dir_all(parent).map_err(|e| Error::io(parent, e))?; } let bytes = self.finish(); let mut f = std::fs::File::create(path).map_err(|e| Error::io(path, e))?; f.write_all(&bytes).map_err(|e| Error::io(path, e))?; Ok(()) } } #[cfg(test)] mod tests { use super::*; #[test] fn crc32_matches_the_known_vector() { // The canonical check value for CRC-32/ISO-HDLC over "123456789". assert_eq!(crc32(b"123456789"), 0xCBF4_3926); assert_eq!(crc32(b""), 0); } #[test] fn produces_a_recognizable_archive() { let mut z = ZipBuilder::new(); z.add_text("imsmanifest.xml", ""); z.add_text("quiz.xml", ""); let bytes = z.finish(); assert_eq!(&bytes[0..4], b"PK\x03\x04", "starts with a local header"); // End-of-central-directory signature appears near the end. let eocd = bytes .windows(4) .rposition(|w| w == b"PK\x05\x06") .expect("has an end-of-central-directory record"); assert_eq!( u16::from_le_bytes([bytes[eocd + 10], bytes[eocd + 11]]), 2, "records two entries" ); assert!(bytes.windows(15).any(|w| w == b"imsmanifest.xml")); } #[test] fn output_is_byte_for_byte_reproducible() { let build = || { let mut z = ZipBuilder::new(); z.add_text("a.xml", ""); z.finish() }; assert_eq!(build(), build()); } #[test] fn empty_archive_is_valid() { let bytes = ZipBuilder::new().finish(); assert_eq!(&bytes[0..4], b"PK\x05\x06"); assert_eq!(bytes.len(), 22); } }