665bfac0b339
entry_files.rs
//! The source files a frame entry on disk was made of (#3184): stored with the pixels, checked
//! when the entry is used. Only the files that frame read are looked at, never every file of the
//! project.
//!
//! Layout (little endian), before the frame's pixel payload:
//! `u32 count`, then per file `u32 path length`, the path (UTF-8), a tag byte and its fields:
//! `0` a file on disk (`u64 size`, `u8 has time`, `i128 time`: nanoseconds since the Unix epoch,
//! negative before it), `1` bytes from the browser's file table (`u64 size`, `u64 content
//! hash`), `2` a file that could not be read.
use std::sync::Arc;
use super::VirtualFileId;
use crate::reads::{FileStamp, MAX_READ_FILES, ReadFile, ReadFiles};
/// Longest path an entry stores (bytes): a longer one is not a path this app opened.
const MAX_PATH_BYTES: usize = 1 << 16;
/// A file's identity as a frame entry keeps it.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum EntryStamp {
/// Size and modification time (nanoseconds since the Unix epoch, negative before it) on
/// disk.
Native { len: u64, modified: Option<i128> },
/// Size and content hash from the [`VirtualFileId`] hook (the browser's file table).
Virtual { len: u64, hash: u64 },
/// It could not be read when the frame was made: it still must not be readable.
Missing,
}
/// One file of a frame entry.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct EntryFile {
pub path: Arc<str>,
pub stamp: EntryStamp,
}
/// Every file a frame entry was made of.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct EntryFiles(Vec<EntryFile>);
impl EntryFiles {
/// The list to store for a frame that read `files`: `None` when the frame can't be checked
/// against its files later (the list is incomplete, or a file from memory has no identity),
/// so the frame must not be stored. Native stamps are the ones the files were read with,
/// never a fresh look at the disk (a file changed during the render keeps the old one).
pub fn of(files: &ReadFiles, virtual_id: Option<VirtualFileId<'_>>) -> Option<EntryFiles> {
if !files.is_complete() {
return None;
}
let mut out = Vec::with_capacity(files.len());
for f in files.files() {
let stamp = match f.stamp {
FileStamp::Native { len, modified } => EntryStamp::Native { len, modified },
FileStamp::Virtual => {
let (len, hash) = virtual_id.and_then(|id| id(&f.path))?;
EntryStamp::Virtual { len, hash }
}
FileStamp::Missing => EntryStamp::Missing,
};
out.push(EntryFile { path: f.path.clone(), stamp });
}
Some(EntryFiles(out))
}
/// The listed files.
pub fn files(&self) -> &[EntryFile] {
&self.0
}
/// The number of listed files.
pub fn len(&self) -> usize {
self.0.len()
}
/// Whether no files are listed.
pub fn is_empty(&self) -> bool {
self.0.is_empty()
}
/// The files as a render reports them (to keep with the frame in memory).
pub fn to_read_files(&self) -> ReadFiles {
self.0
.iter()
.map(|f| {
let stamp = match f.stamp {
EntryStamp::Native { len, modified } => FileStamp::Native { len, modified },
EntryStamp::Virtual { .. } => FileStamp::Virtual,
EntryStamp::Missing => FileStamp::Missing,
};
ReadFile::new(f.path.clone(), stamp)
})
.collect()
}
/// Whether every file still is what the frame was made of: one `metadata` call per file
/// (and the hook for files from memory).
pub fn unchanged(&self, virtual_id: Option<VirtualFileId<'_>>) -> bool {
self.0.iter().all(|f| file_unchanged(f, virtual_id))
}
/// Appends the list to `out` in little-endian binary form.
pub(super) fn encode(&self, out: &mut Vec<u8>) {
out.extend_from_slice(&(self.0.len() as u32).to_le_bytes());
for f in &self.0 {
out.extend_from_slice(&(f.path.len() as u32).to_le_bytes());
out.extend_from_slice(f.path.as_bytes());
match f.stamp {
EntryStamp::Native { len, modified } => {
out.push(0);
out.extend_from_slice(&len.to_le_bytes());
out.push(u8::from(modified.is_some()));
out.extend_from_slice(&modified.unwrap_or(0).to_le_bytes());
}
EntryStamp::Virtual { len, hash } => {
out.push(1);
out.extend_from_slice(&len.to_le_bytes());
out.extend_from_slice(&hash.to_le_bytes());
}
EntryStamp::Missing => out.push(2),
}
}
}
/// The list at the start of `p` and what follows it; `None` when it is damaged.
pub(super) fn decode(p: &[u8]) -> Option<(EntryFiles, &[u8])> {
let mut r = Reader(p);
let n = r.u32()? as usize;
if n > MAX_READ_FILES {
return None;
}
let mut out = Vec::with_capacity(n);
for _ in 0..n {
let len = r.u32()? as usize;
if len > MAX_PATH_BYTES {
return None;
}
let path: Arc<str> = std::str::from_utf8(r.take(len)?).ok()?.into();
let stamp = match r.u8()? {
0 => {
let len = r.u64()?;
let has = r.u8()?;
let t = r.i128()?;
match has {
0 => EntryStamp::Native { len, modified: None },
1 => EntryStamp::Native { len, modified: Some(t) },
_ => return None,
}
}
1 => EntryStamp::Virtual { len: r.u64()?, hash: r.u64()? },
2 => EntryStamp::Missing,
_ => return None,
};
out.push(EntryFile { path, stamp });
}
Some((EntryFiles(out), r.0))
}
}
/// Whether the file still matches its stored stamp, by its native stamp or by its in-memory identity.
fn file_unchanged(f: &EntryFile, virtual_id: Option<VirtualFileId<'_>>) -> bool {
let from_memory = || virtual_id.and_then(|id| id(&f.path));
match f.stamp {
EntryStamp::Native { len, modified } => FileStamp::native(&f.path) == Some(FileStamp::Native { len, modified }),
EntryStamp::Virtual { len, hash } => from_memory() == Some((len, hash)),
// (a folder at the path is still not a file to read)
EntryStamp::Missing => !std::fs::metadata(&*f.path).is_ok_and(|m| m.is_file()) && from_memory().is_none(),
}
}
/// Reads little-endian fields off the front of a byte slice.
struct Reader<'a>(&'a [u8]);
impl<'a> Reader<'a> {
/// Takes the next `n` bytes, or `None` when fewer remain.
fn take(&mut self, n: usize) -> Option<&'a [u8]> {
let head = self.0.get(..n)?;
self.0 = self.0.get(n..)?;
Some(head)
}
/// Reads one byte.
fn u8(&mut self) -> Option<u8> {
self.take(1)?.first().copied()
}
/// Reads a little-endian `u32`.
fn u32(&mut self) -> Option<u32> {
Some(u32::from_le_bytes(self.take(4)?.try_into().ok()?))
}
/// Reads a little-endian `u64`.
fn u64(&mut self) -> Option<u64> {
Some(u64::from_le_bytes(self.take(8)?.try_into().ok()?))
}
/// Reads a little-endian `i128`.
fn i128(&mut self) -> Option<i128> {
Some(i128::from_le_bytes(self.take(16)?.try_into().ok()?))
}
}
#[cfg(test)]
mod tests {
use super::*;
/// A sample list of native, missing and virtual files for the tests.
fn files() -> ReadFiles {
[
ReadFile::new("/a.png", FileStamp::Native { len: 3, modified: Some(9) }),
ReadFile::new("/b.png", FileStamp::Native { len: 4, modified: None }),
// Before 1970, and past where `u64` nanoseconds end (2554).
ReadFile::new("/d.png", FileStamp::Native { len: 5, modified: Some(-86_400_000_000_000) }),
ReadFile::new("/e.png", FileStamp::Native { len: 6, modified: Some(i128::from(u64::MAX) + 1) }),
ReadFile::new("/c.png", FileStamp::Missing),
ReadFile::new("/v.mov", FileStamp::Virtual),
]
.into_iter()
.collect()
}
#[test]
fn lists_round_trip_and_damage_is_caught() {
let id = |p: &str| (p == "/v.mov").then_some((8, 77));
let list = EntryFiles::of(&files(), Some(&id)).unwrap();
assert_eq!(list.files()[5].stamp, EntryStamp::Virtual { len: 8, hash: 77 });
let mut bytes = vec![];
list.encode(&mut bytes);
bytes.extend_from_slice(b"rest");
let (back, rest) = EntryFiles::decode(&bytes).unwrap();
assert_eq!((back, rest), (list.clone(), &b"rest"[..]));
assert_eq!(list.to_read_files(), files());
// Every truncation is caught (never a panic, never a shorter list).
let mut plain = vec![];
list.encode(&mut plain);
for n in 0..plain.len() {
assert!(EntryFiles::decode(&plain[..n]).is_none(), "cut at {n}");
}
// Bad tags and counts.
let mut bad = plain.clone();
bad[0..4].copy_from_slice(&u32::MAX.to_le_bytes());
assert!(EntryFiles::decode(&bad).is_none());
}
#[test]
fn frames_that_cant_be_checked_are_not_stored() {
let mut incomplete = files();
incomplete.mark_incomplete();
let id = |_: &str| Some((1, 1));
assert!(EntryFiles::of(&incomplete, Some(&id)).is_none(), "an incomplete list");
assert!(EntryFiles::of(&files(), None).is_none(), "a file from memory without the hook");
assert!(EntryFiles::of(&ReadFiles::default(), None).is_some_and(|l| l.is_empty()), "a frame that reads no file");
}
#[test]
fn the_check_looks_at_the_listed_files() {
let dir = std::env::temp_dir().join(format!("effectcraft-entry-files-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
let p = dir.join("f.bin");
std::fs::write(&p, b"abc").unwrap();
let path = p.to_string_lossy().to_string();
let gone = dir.join("gone.bin").to_string_lossy().to_string();
let stamp = FileStamp::native(&path).unwrap();
let read: ReadFiles = [ReadFile::new(path.as_str(), stamp), ReadFile::new(gone.as_str(), FileStamp::Missing)].into_iter().collect();
let list = EntryFiles::of(&read, None).unwrap();
assert!(list.unchanged(None));
std::fs::write(&p, b"abcd").unwrap();
assert!(!list.unchanged(None), "a new size");
std::fs::write(&gone, b"x").unwrap();
let list = EntryFiles::of(&[ReadFile::new(gone.as_str(), FileStamp::Missing)].into_iter().collect(), None).unwrap();
assert!(!list.unchanged(None), "a missing file that is back");
let v: ReadFiles = [ReadFile::new("/v", FileStamp::Virtual)].into_iter().collect();
let one = |_: &str| Some((1, 1));
let two = |_: &str| Some((1, 2));
let list = EntryFiles::of(&v, Some(&one)).unwrap();
assert!(list.unchanged(Some(&one)) && !list.unchanged(Some(&two)) && !list.unchanged(None));
let _ = std::fs::remove_dir_all(&dir);
}
}
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.