88f5a00e389b
asset_io.rs
//! Reading linked files' bytes for the document model ([`designcraft_doc::asset_data`]): the
//! [`Loader`] every [`crate::Session`] installs. Files are read through [`crate::io`] (the
//! automation roots of the loading thread apply) and only ever yield the bytes the link record
//! names: other bytes at the path are [`Unavailable::Modified`] and are never handed out.
//!
//! The web build installs no loader: its linked assets are [`Unavailable::NoLoader`].
use std::path::{Path, PathBuf};
use designcraft_doc::asset_data::{Loaded, Loader, MAX_LINKED_BYTES};
use designcraft_doc::{Fingerprint, LinkedSource, Unavailable};
/// Read linked files with [`FileLoader`] in this process (on the web: nothing to install).
pub fn install() {
#[cfg(not(target_arch = "wasm32"))]
designcraft_doc::asset_data::install_loader(std::sync::Arc::new(FileLoader));
}
/// The engine's [`Loader`]: [`read_linked`].
pub struct FileLoader;
impl Loader for FileLoader {
fn load(&self, source: &LinkedSource, trusted: Option<Fingerprint>) -> Result<Loaded, Unavailable> {
read_linked(source, trusted)
}
fn load_current(&self, source: &LinkedSource) -> Result<Vec<u8>, Unavailable> {
read_current(source)
}
fn holds(&self, source: &LinkedSource, trusted: Option<Fingerprint>, kept: &[u8]) -> Result<Option<Fingerprint>, Unavailable> {
still_holds(source, trusted, kept)
}
}
/// Whether a candidate file ([`candidates`]) still holds `kept`, the bytes read for `source`
/// earlier ([`Loader::holds`]): one of `source.len` bytes with the recorded or `trusted`
/// fingerprint (nothing is read), else one whose content hash is `source.hash`, or without a
/// hash whose bytes are `kept`. → the fingerprint of a file that was read to tell.
pub fn still_holds(source: &LinkedSource, trusted: Option<Fingerprint>, kept: &[u8]) -> Result<Option<Fingerprint>, Unavailable> {
let mut seen = false;
for path in candidates(source) {
let Some(meta) = crate::io::file_metadata(&path) else { continue };
seen = true;
let found = fingerprint_from(&meta);
if found.size != source.len {
continue;
}
if has_time(&found) && (Some(found) == source.fingerprint || Some(found) == trusted) {
return Ok(None);
}
let Ok(bytes) = crate::io::read_capped(&path, source.len) else { continue };
let same = match &source.hash {
Some(hash) => *hash == content_hash(&bytes),
None => bytes == kept,
};
if same {
return Ok(has_time(&found).then_some(found));
}
}
Err(if seen { Unavailable::Modified } else { Unavailable::Missing })
}
/// The bytes of the first candidate file that exists, whatever they are (no fingerprint or hash
/// check): what an export uses for a link whose file has changed.
pub fn read_current(source: &LinkedSource) -> Result<Vec<u8>, Unavailable> {
for path in candidates(source) {
let Some(meta) = crate::io::file_metadata(&path) else { continue };
if meta.len() > MAX_LINKED_BYTES {
return Err(Unavailable::TooLarge);
}
if let Ok(bytes) = crate::io::read_capped(&path, MAX_LINKED_BYTES) {
return Ok(bytes);
}
}
Err(Unavailable::Missing)
}
/// `sha256:` and the hex digits of the SHA-256 of `bytes` ([`designcraft_doc::Asset::link_hash`]).
pub fn content_hash(bytes: &[u8]) -> String {
use sha2::Digest;
use std::fmt::Write;
let digest = sha2::Sha256::digest(bytes);
let mut out = String::with_capacity(7 + 64);
out.push_str("sha256:");
for b in digest {
let _ = write!(out, "{b:02x}");
}
out
}
/// Size and modification time (whole seconds) from a file's metadata, as link records store them.
pub fn fingerprint_from(meta: &crate::io::Metadata) -> Fingerprint {
let mtime = meta
.modified()
.ok()
.and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
.map(|d| i64::try_from(d.as_secs()).unwrap_or(i64::MAX))
.unwrap_or(0);
Fingerprint { size: meta.len(), mtime }
}
/// Whether `f` has a modification time to tell the file by: [`fingerprint_from`] gives 0 where
/// the file system reports none, and two such files of one size would look the same.
pub fn has_time(f: &Fingerprint) -> bool {
f.mtime != 0
}
/// The files that may hold `source`'s bytes, in the order they are tried: the absolute path,
/// then the relative one resolved against the document. Paths [`crate::io::document_path`]
/// refuses are left out.
pub fn candidates(source: &LinkedSource) -> Vec<PathBuf> {
let document = source.document.as_deref();
let mut out: Vec<PathBuf> = crate::io::document_path(&source.path, document).into_iter().collect();
if let (Some(relative), Some(document)) = (source.relative.as_deref(), document)
&& let Ok(p) = crate::io::document_path(relative, Some(document))
&& !out.contains(&p)
{
out.push(p);
}
out
}
/// Why one candidate file doesn't serve.
enum Miss {
Absent,
Modified,
TooLarge,
}
/// The bytes of the first candidate file ([`candidates`]) that holds `source`'s bytes: one of
/// `source.len` bytes whose fingerprint is `source.fingerprint` or `trusted`, or whose content
/// hash is `source.hash`. A source that records neither fingerprint nor hash is taken by its
/// size. The fingerprint of a file accepted by its hash is returned with the bytes.
pub fn read_linked(source: &LinkedSource, trusted: Option<Fingerprint>) -> Result<Loaded, Unavailable> {
if source.len > MAX_LINKED_BYTES {
return Err(Unavailable::TooLarge);
}
let mut worst = Miss::Absent;
for path in candidates(source) {
match read_candidate(&path, source, trusted) {
Ok(loaded) => return Ok(loaded),
Err(Miss::Absent) => {}
Err(miss @ Miss::TooLarge) => worst = miss,
Err(Miss::Modified) => {
if !matches!(worst, Miss::TooLarge) {
worst = Miss::Modified;
}
}
}
}
Err(match worst {
Miss::Absent => Unavailable::Missing,
Miss::Modified => Unavailable::Modified,
Miss::TooLarge => Unavailable::TooLarge,
})
}
fn read_candidate(path: &Path, source: &LinkedSource, trusted: Option<Fingerprint>) -> Result<Loaded, Miss> {
let meta = crate::io::file_metadata(path).ok_or(Miss::Absent)?;
let found = fingerprint_from(&meta);
if found.size > MAX_LINKED_BYTES {
return Err(Miss::TooLarge);
}
if found.size != source.len {
return Err(Miss::Modified);
}
let known = has_time(&found) && (Some(found) == source.fingerprint || Some(found) == trusted);
if !known && source.hash.is_none() && source.fingerprint.is_some() {
// Nothing to tell the bytes by.
return Err(Miss::Modified);
}
// At most one byte past the size: a file that grew since is caught without reading it all.
let bytes = crate::io::read_capped(path, source.len).map_err(|_| Miss::Absent)?;
if bytes.len() as u64 != source.len {
return Err(Miss::Modified);
}
if known {
return Ok(Loaded { bytes, fingerprint: None });
}
match &source.hash {
Some(hash) if *hash != content_hash(&bytes) => Err(Miss::Modified),
Some(_) => Ok(Loaded { bytes, fingerprint: Some(found) }),
None => Ok(Loaded { bytes, fingerprint: None }),
}
}
#[cfg(test)]
mod tests {
use super::*;
use designcraft_doc::AssetData;
struct Dir(PathBuf);
impl Dir {
fn new(name: &str) -> Self {
let dir = std::env::temp_dir().join(format!("dc-asset-io-{name}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
Dir(dir)
}
}
impl Drop for Dir {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.0);
}
}
/// The link record of the file at `path` as it is now.
fn source_of(path: &Path) -> LinkedSource {
let bytes = std::fs::read(path).unwrap();
LinkedSource {
path: path.to_string_lossy().into_owned(),
relative: None,
document: None,
len: bytes.len() as u64,
fingerprint: Some(fingerprint_from(&std::fs::metadata(path).unwrap())),
hash: Some(content_hash(&bytes)),
}
}
/// Set the file's modification time `secs` seconds into the past.
fn age(path: &Path, secs: u64) {
let file = std::fs::OpenOptions::new().write(true).open(path).unwrap();
file.set_modified(std::time::SystemTime::now() - std::time::Duration::from_secs(secs)).unwrap();
}
#[test]
fn content_hashes_are_sha256_hex() {
assert_eq!(content_hash(b"abc"), "sha256:ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad");
}
#[test]
fn a_linked_file_is_read_when_it_holds_the_recorded_bytes() {
let dir = Dir::new("read");
let path = dir.0.join("a.png");
std::fs::write(&path, b"original").unwrap();
let source = source_of(&path);
assert_eq!(read_linked(&source, None).ok().map(|l| (l.bytes, l.fingerprint)), Some((b"original".to_vec(), None)));
// Same bytes, another time: accepted by the hash, and the new fingerprint returned.
age(&path, 1000);
let now = fingerprint_from(&std::fs::metadata(&path).unwrap());
let loaded = read_linked(&source, None).ok().unwrap();
assert_eq!((loaded.bytes.as_slice(), loaded.fingerprint), (b"original".as_slice(), Some(now)));
assert!(read_linked(&source, Some(now)).is_ok_and(|l| l.fingerprint.is_none()), "a trusted fingerprint needs no hash");
let unverifiable = LinkedSource { hash: None, ..source.clone() };
assert_eq!(read_linked(&unverifiable, None).err(), Some(Unavailable::Modified), "nothing to tell the bytes by");
}
#[test]
fn other_bytes_at_the_path_are_modified_and_a_missing_file_is_missing() {
let dir = Dir::new("modified");
let path = dir.0.join("a.png");
std::fs::write(&path, b"original").unwrap();
let source = source_of(&path);
std::fs::write(&path, b"changed!").unwrap();
age(&path, 1000);
assert_eq!(read_linked(&source, None).err(), Some(Unavailable::Modified), "same size, other bytes");
std::fs::write(&path, b"longer than before").unwrap();
assert_eq!(read_linked(&source, None).err(), Some(Unavailable::Modified), "another size");
std::fs::remove_file(&path).unwrap();
assert_eq!(read_linked(&source, None).err(), Some(Unavailable::Missing));
let too_large = LinkedSource { len: MAX_LINKED_BYTES + 1, ..source };
assert_eq!(read_linked(&too_large, None).err(), Some(Unavailable::TooLarge));
}
#[test]
fn the_relative_path_serves_when_the_absolute_one_does_not() {
let dir = Dir::new("relative");
std::fs::create_dir_all(dir.0.join("moved/links")).unwrap();
let away = dir.0.join("moved/links/a.png");
std::fs::write(&away, b"original").unwrap();
let mut source = source_of(&away);
source.path = dir.0.join("gone/links/a.png").to_string_lossy().into_owned();
assert_eq!(read_linked(&source, None).err(), Some(Unavailable::Missing));
source.relative = Some("links/a.png".into());
source.document = Some(dir.0.join("moved/doc.dcx"));
assert_eq!(read_linked(&source, None).ok().map(|l| l.bytes), Some(b"original".to_vec()));
// A changed file at the absolute path doesn't hide the one that holds the bytes.
std::fs::create_dir_all(dir.0.join("gone/links")).unwrap();
std::fs::write(dir.0.join("gone/links/a.png"), b"other!!!").unwrap();
age(&dir.0.join("gone/links/a.png"), 1000);
assert_eq!(read_linked(&source, None).ok().map(|l| l.bytes), Some(b"original".to_vec()));
}
/// A time of 0 is what a file system without times gives: it can't tell two files apart.
#[test]
fn a_file_without_a_time_is_told_by_its_hash() {
let dir = Dir::new("no-time");
let path = dir.0.join("a.png");
let at_epoch = |p: &Path| std::fs::OpenOptions::new().write(true).open(p).unwrap().set_modified(std::time::UNIX_EPOCH).unwrap();
std::fs::write(&path, b"original").unwrap();
at_epoch(&path);
let source = source_of(&path);
assert_eq!(source.fingerprint.map(|f| f.mtime), Some(0));
std::fs::write(&path, b"changed!").unwrap();
at_epoch(&path);
assert_eq!(read_linked(&source, None).err(), Some(Unavailable::Modified));
}
/// Through the installed loader and the store: a file changed on disk is never adopted.
#[test]
fn asset_data_loads_through_the_installed_loader() {
install();
let dir = Dir::new("installed");
let path = dir.0.join("a.png");
std::fs::write(&path, b"original").unwrap();
let data = AssetData::linked(source_of(&path));
let changed = AssetData::linked(source_of(&path));
assert_eq!(data.load().ok().map(|b| b.to_vec()), Some(b"original".to_vec()));
assert!(data.resident().is_some());
std::fs::write(&path, b"changed!").unwrap();
age(&path, 1000);
assert_eq!(data.load().ok().map(|b| b.to_vec()), Some(b"original".to_vec()), "kept bytes are the recorded ones");
assert_eq!(changed.load().err(), Some(Unavailable::Modified));
assert!(changed.resident().is_none(), "nothing adopted");
std::fs::remove_file(&path).unwrap();
data.evict();
assert_eq!(data.load().err(), Some(Unavailable::Missing));
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.