mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-16 23:42:27 +00:00
183 lines
8.4 KiB
Rust
183 lines
8.4 KiB
Rust
//! An archive open for reading: entry-count guard, duplicate names, budgeted entry reads.
|
|
|
|
use std::borrow::Cow;
|
|
use std::io::{Cursor, Read};
|
|
|
|
use crate::preflight::{ReadError, read_entry};
|
|
use crate::{Budget, Error, check_entry_count};
|
|
|
|
/// What an [`Archive`] refuses to exceed. Both numbers are the caller's.
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
|
|
pub struct Limits {
|
|
/// Most entries the archive may declare.
|
|
pub max_entries: u64,
|
|
/// Most bytes all the entries read from the archive may expand to together.
|
|
pub max_total_bytes: u64,
|
|
}
|
|
|
|
/// A ZIP archive in memory. Nothing is decompressed until an entry is read.
|
|
///
|
|
/// A clone shares the parsed directory and the bytes, and carries a copy of the budget: a
|
|
/// caller that reads through a clone keeps its own count.
|
|
#[derive(Clone)]
|
|
pub struct Archive<'a> {
|
|
zip: zip::ZipArchive<Cursor<&'a [u8]>>,
|
|
budget: Budget,
|
|
duplicates: bool,
|
|
}
|
|
|
|
const CENTRAL_HEADER: &[u8; 4] = b"PK\x01\x02";
|
|
const CENTRAL_HEADER_LEN: usize = 46;
|
|
|
|
/// The central directory headers that follow one another from `start`, counted up to `stop`.
|
|
fn count_central_headers(bytes: &[u8], start: u64, stop: usize) -> usize {
|
|
let u16_at = |at: usize| bytes.get(at..at.checked_add(2)?).map(|b| usize::from(u16::from_le_bytes([b[0], b[1]])));
|
|
let Ok(mut at) = usize::try_from(start) else { return 0 };
|
|
let mut count = 0;
|
|
while count < stop && bytes.get(at..).is_some_and(|b| b.starts_with(CENTRAL_HEADER)) {
|
|
let (Some(name), Some(extra), Some(comment)) = (u16_at(at + 28), u16_at(at + 30), u16_at(at + 32)) else { break };
|
|
count += 1;
|
|
at = at.saturating_add(CENTRAL_HEADER_LEN + name + extra + comment);
|
|
}
|
|
count
|
|
}
|
|
|
|
impl<'a> Archive<'a> {
|
|
/// Indexes `bytes`. The declared entry count is checked against
|
|
/// [`Limits::max_entries`] before `zip` parses the central directory, and again after.
|
|
pub fn open(bytes: &'a [u8], limits: Limits) -> Result<Self, Error> {
|
|
check_entry_count(bytes, limits.max_entries)?;
|
|
let zip = zip::ZipArchive::new(Cursor::new(bytes)).map_err(|e| Error::NotZip(e.to_string()))?;
|
|
let found = zip.len() as u64;
|
|
if found > limits.max_entries {
|
|
return Err(Error::TooManyEntries { declared: found, limit: limits.max_entries });
|
|
}
|
|
// `zip` keeps one entry per name, so a directory with more headers than `zip` has entries
|
|
// repeats a name.
|
|
let duplicates = count_central_headers(bytes, zip.central_directory_start(), zip.len().saturating_add(1)) > zip.len();
|
|
Ok(Archive { zip, budget: Budget::new("archive", limits.max_total_bytes), duplicates })
|
|
}
|
|
|
|
/// The number of distinct entry names.
|
|
pub fn len(&self) -> usize {
|
|
self.zip.len()
|
|
}
|
|
|
|
pub fn is_empty(&self) -> bool {
|
|
self.zip.is_empty()
|
|
}
|
|
|
|
/// The name at `index`, copied on demand so callers can process hostile directories without
|
|
/// retaining a second copy of every potentially large name.
|
|
pub fn entry_name(&mut self, index: usize) -> Result<Option<String>, Error> {
|
|
if index >= self.zip.len() {
|
|
return Ok(None);
|
|
}
|
|
let file = self.zip.by_index_raw(index).map_err(|error| Error::NotZip(error.to_string()))?;
|
|
let name = file.name().map_err(|error| Error::NotZip(error.to_string()))?;
|
|
Ok(Some(name.into_owned()))
|
|
}
|
|
|
|
/// Whether the entry at `index` is a directory according to ZIP filename conventions.
|
|
pub fn entry_is_dir(&mut self, index: usize) -> Result<Option<bool>, Error> {
|
|
if index >= self.zip.len() {
|
|
return Ok(None);
|
|
}
|
|
let file = self.zip.by_index_raw(index).map_err(|error| Error::NotZip(error.to_string()))?;
|
|
Ok(Some(file.is_dir()))
|
|
}
|
|
|
|
/// Do two entries share a name? `zip` then keeps one of them, and which one a writer meant
|
|
/// is not known: a format that must not guess refuses the archive.
|
|
pub fn has_duplicate_names(&self) -> bool {
|
|
self.duplicates
|
|
}
|
|
|
|
/// Do two entries' compressed data ranges overlap? A format that stores many files in one
|
|
/// archive can refuse aliases so one payload cannot be expanded and retained repeatedly.
|
|
pub fn has_overlapping_files(&mut self) -> Result<bool, Error> {
|
|
self.zip.has_overlapping_files().map_err(|e| Error::NotZip(e.to_string()))
|
|
}
|
|
|
|
/// The entry names in the archive's order, folders included. A name that is not text is
|
|
/// left out.
|
|
pub fn names(&self) -> impl Iterator<Item = Cow<'_, str>> {
|
|
self.zip.file_names().filter_map(Result::ok)
|
|
}
|
|
|
|
/// Is there an entry `name` (exactly as stored)?
|
|
pub fn contains(&self, name: &str) -> bool {
|
|
self.zip.index_for_name(name).is_some()
|
|
}
|
|
|
|
/// The size entry `name` declares. It is a claim, not a measurement.
|
|
pub fn declared_size(&mut self, name: &str) -> Option<u64> {
|
|
let index = self.zip.index_for_name(name)?;
|
|
self.zip.by_index_raw(index).ok().map(|f| f.size())
|
|
}
|
|
|
|
/// The size entry `name` takes in the archive, compressed. With [`Archive::declared_size`] it
|
|
/// gives the compression ratio the entry claims.
|
|
pub fn compressed_size(&mut self, name: &str) -> Option<u64> {
|
|
let index = self.zip.index_for_name(name)?;
|
|
self.zip.by_index_raw(index).ok().map(|f| f.compressed_size())
|
|
}
|
|
|
|
/// Is `name` stored without compression? The answer lets a format with in-memory source bytes
|
|
/// apply an output-size cap to compressed entries while bounding stored reads by source size.
|
|
pub fn is_stored(&mut self, name: &str) -> Option<bool> {
|
|
let index = self.zip.index_for_name(name)?;
|
|
self.zip.by_index_raw(index).ok().map(|f| f.compression() == zip::CompressionMethod::Stored)
|
|
}
|
|
|
|
/// The first `n` bytes of entry `name` (all of it when it is shorter), or `None` when there
|
|
/// is no such entry: for telling a file by its signature without inflating it. The bytes are
|
|
/// charged to the total; a total with less left than the bytes wanted refuses before reading.
|
|
///
|
|
/// The entry's checksum is not checked: it covers the whole entry.
|
|
pub fn read_head(&mut self, name: &str, n: usize) -> Result<Option<Vec<u8>>, Error> {
|
|
let Some(index) = self.zip.index_for_name(name) else { return Ok(None) };
|
|
let entry = |msg: String| Error::Entry { name: name.to_string(), msg };
|
|
let f = self.zip.by_index(index).map_err(|e| entry(e.to_string()))?;
|
|
// Never more than the entry declares: a shorter entry costs only what it has.
|
|
let want = (n as u64).min(f.size());
|
|
if self.budget.remaining() < want {
|
|
return Err(Error::BudgetSpent { name: name.to_string(), limit: self.budget.limit() });
|
|
}
|
|
let mut out = Vec::with_capacity(n.min(64 * 1024));
|
|
f.take(want).read_to_end(&mut out).map_err(|e| entry(e.to_string()))?;
|
|
self.budget.charge(out.len() as u64).map_err(|e| Error::BudgetSpent { name: name.to_string(), limit: e.limit })?;
|
|
Ok(Some(out))
|
|
}
|
|
|
|
/// The bytes of entry `name`, or `None` when there is no such entry.
|
|
///
|
|
/// The entry may declare, and expand to, at most `max` bytes, and at most what is left of
|
|
/// [`Limits::max_total_bytes`]. An entry that expands past the size it declares is refused.
|
|
/// Only the bytes of a read that succeeds are charged to the total.
|
|
pub fn read(&mut self, name: &str, max: u64) -> Result<Option<Vec<u8>>, Error> {
|
|
let Some(index) = self.zip.index_for_name(name) else { return Ok(None) };
|
|
let entry = |msg: String| Error::Entry { name: name.to_string(), msg };
|
|
let f = self.zip.by_index(index).map_err(|e| entry(e.to_string()))?;
|
|
let declared = f.size();
|
|
match read_entry(f, declared, max, &mut self.budget) {
|
|
Ok(data) => Ok(Some(data)),
|
|
Err(ReadError::DeclaredTooLarge { limit, .. }) | Err(ReadError::Overrun { limit }) => {
|
|
Err(Error::EntryTooLarge { name: name.to_string(), limit })
|
|
}
|
|
Err(ReadError::Budget(e)) => Err(Error::BudgetSpent { name: name.to_string(), limit: e.limit }),
|
|
Err(ReadError::Io(e)) => Err(entry(e.to_string())),
|
|
}
|
|
}
|
|
|
|
/// The total budget: what the entries read so far have used, and what is left.
|
|
pub fn budget(&self) -> &Budget {
|
|
&self.budget
|
|
}
|
|
|
|
/// The total budget, for a caller with its own charging rule (charging a failed read, say).
|
|
pub fn budget_mut(&mut self) -> &mut Budget {
|
|
&mut self.budget
|
|
}
|
|
}
|