Files
coursebank/src/util/zipfile.rs
T
alexmandClaude c8d6f4a5dd
Pipeline / check (pull_request) Successful in 12m21s
Pipeline / docs (pull_request) Skipped
Pipeline / nightly (pull_request) Skipped
Pipeline / release (pull_request) Skipped
Name Scienting as the copyright holder and contributor
Replace 'Scientific Computing Studio' in the source headers, the Cargo.toml
authors, and the LICENSE contributor line. pixi.toml still has the old
authors line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014zNf4shD4zaCKLucZWPYL9
2026-10-20 00:21:19 -04:00

247 lines
8.1 KiB
Rust

// 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<u8>,
/// 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<Entry>,
body: Vec<u8>,
}
/// 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<Vec<u8>>) {
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<u8> {
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", "<manifest/>");
z.add_text("quiz.xml", "<questestinterop/>");
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", "<a/>");
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);
}
}