- Project::open canonicalises the root (no \?\ prefix on Windows where safe); typed errors for missing and non-directory paths. - Lazy children(dir): dirs first, case-insensitive; kind, ignored flag and role (vendor/ library, node_modules/ excluded, .git hidden). - Ignore rules via the ignore crate: .gitignore, .ignore, .git/info/exclude, global git excludes, with git precedence. - Watcher: std-only polling (100 ms, watched dirs only) with create/modify/remove/rename events and a Failed event on root loss. notify is CC0-1.0 and fails cargo deny; owner decision pending. - read_text with a 32 MiB cap, UTF-8 + BOM, typed InvalidUtf8 and UnsupportedEncoding; write_atomic via temp file + rename, keeping permissions and refusing read-only files. - 28 tests on temp dirs (30 on Unix: permission and symlink write tests). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
216 lines
7.8 KiB
Rust
216 lines
7.8 KiB
Rust
//! Reading and writing files safely.
|
|
//!
|
|
//! Reads are capped ([`DEFAULT_READ_LIMIT`]) because files on disk are
|
|
//! untrusted. Text is UTF-8, with or without a byte order mark; other
|
|
//! encodings are detected by their BOM and reported, not guessed. Writes go
|
|
//! to a temporary file in the same directory that is then renamed over the
|
|
//! target, so a crash never leaves a half-written file behind.
|
|
|
|
use std::fs::{self, File, OpenOptions};
|
|
use std::io::{self, Read, Write};
|
|
use std::path::{Path, PathBuf};
|
|
use std::sync::atomic::{AtomicU64, Ordering};
|
|
|
|
use crate::VfsError;
|
|
|
|
/// Default read limit: 32 MiB.
|
|
pub const DEFAULT_READ_LIMIT: u64 = 32 * 1024 * 1024;
|
|
|
|
/// The UTF-8 byte order mark.
|
|
const UTF8_BOM: &[u8] = &[0xEF, 0xBB, 0xBF];
|
|
|
|
/// Byte order marks of encodings that are recognised but not decoded yet,
|
|
/// longest first so UTF-32LE is not mistaken for UTF-16LE.
|
|
const OTHER_BOMS: &[(&[u8], &str)] = &[
|
|
(&[0xFF, 0xFE, 0x00, 0x00], "UTF-32LE"),
|
|
(&[0x00, 0x00, 0xFE, 0xFF], "UTF-32BE"),
|
|
(&[0xFF, 0xFE], "UTF-16LE"),
|
|
(&[0xFE, 0xFF], "UTF-16BE"),
|
|
];
|
|
|
|
/// Attempts to find a free temporary file name before giving up.
|
|
const TEMP_ATTEMPTS: u32 = 100;
|
|
|
|
/// Counter that makes temporary file names unique within the process.
|
|
static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0);
|
|
|
|
/// A decoded text file.
|
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
|
pub struct TextFile {
|
|
/// The text, without the byte order mark.
|
|
pub text: String,
|
|
/// The file started with a UTF-8 byte order mark; keep it when saving.
|
|
pub bom: bool,
|
|
}
|
|
|
|
/// Reads at most `limit` bytes of the file at `path`.
|
|
///
|
|
/// # Errors
|
|
/// [`VfsError::NotFound`], [`VfsError::NotAFile`] for a directory,
|
|
/// [`VfsError::TooLarge`] if the file is (or grows while reading) larger than
|
|
/// `limit`, [`VfsError::Io`] for other failures.
|
|
pub fn read_bytes(path: &Path, limit: u64) -> Result<Vec<u8>, VfsError> {
|
|
let file = File::open(path).map_err(|err| VfsError::io(path, err))?;
|
|
let meta = file.metadata().map_err(|err| VfsError::io(path, err))?;
|
|
if meta.is_dir() {
|
|
return Err(VfsError::NotAFile {
|
|
path: path.to_path_buf(),
|
|
});
|
|
}
|
|
let too_large = |size| VfsError::TooLarge {
|
|
path: path.to_path_buf(),
|
|
size,
|
|
limit,
|
|
};
|
|
if meta.len() > limit {
|
|
return Err(too_large(meta.len()));
|
|
}
|
|
let capacity = usize::try_from(meta.len()).unwrap_or(0);
|
|
let mut bytes = Vec::with_capacity(capacity);
|
|
file.take(limit.saturating_add(1))
|
|
.read_to_end(&mut bytes)
|
|
.map_err(|err| VfsError::io(path, err))?;
|
|
let read = u64::try_from(bytes.len()).unwrap_or(u64::MAX);
|
|
if read > limit {
|
|
return Err(too_large(read));
|
|
}
|
|
Ok(bytes)
|
|
}
|
|
|
|
/// Reads the text file at `path` with the [`DEFAULT_READ_LIMIT`].
|
|
///
|
|
/// # Errors
|
|
/// See [`read_text_with_limit`].
|
|
pub fn read_text(path: &Path) -> Result<TextFile, VfsError> {
|
|
read_text_with_limit(path, DEFAULT_READ_LIMIT)
|
|
}
|
|
|
|
/// Reads and decodes the text file at `path`, reading at most `limit` bytes.
|
|
///
|
|
/// # Errors
|
|
/// Everything [`read_bytes`] returns, plus
|
|
/// [`VfsError::UnsupportedEncoding`] for a UTF-16 or UTF-32 BOM and
|
|
/// [`VfsError::InvalidUtf8`] for bytes that are not UTF-8.
|
|
pub fn read_text_with_limit(path: &Path, limit: u64) -> Result<TextFile, VfsError> {
|
|
decode(path, read_bytes(path, limit)?)
|
|
}
|
|
|
|
/// Decodes file contents as UTF-8 with an optional BOM; `path` is only used
|
|
/// in errors.
|
|
///
|
|
/// # Errors
|
|
/// [`VfsError::UnsupportedEncoding`] or [`VfsError::InvalidUtf8`].
|
|
pub fn decode(path: &Path, mut bytes: Vec<u8>) -> Result<TextFile, VfsError> {
|
|
let bom = bytes.starts_with(UTF8_BOM);
|
|
if bom {
|
|
bytes.drain(..UTF8_BOM.len());
|
|
} else if let Some((_, encoding)) = OTHER_BOMS.iter().find(|(mark, _)| bytes.starts_with(mark))
|
|
{
|
|
return Err(VfsError::UnsupportedEncoding {
|
|
path: path.to_path_buf(),
|
|
encoding,
|
|
});
|
|
}
|
|
let offset = if bom { UTF8_BOM.len() } else { 0 };
|
|
match String::from_utf8(bytes) {
|
|
Ok(text) => Ok(TextFile { text, bom }),
|
|
Err(err) => Err(VfsError::InvalidUtf8 {
|
|
path: path.to_path_buf(),
|
|
valid_up_to: err.utf8_error().valid_up_to() + offset,
|
|
}),
|
|
}
|
|
}
|
|
|
|
/// Writes `text` to `path` atomically as UTF-8, with a BOM if `bom` is set.
|
|
///
|
|
/// # Errors
|
|
/// See [`write_atomic`].
|
|
pub fn write_text(path: &Path, text: &str, bom: bool) -> Result<(), VfsError> {
|
|
let mut bytes = Vec::with_capacity(text.len() + UTF8_BOM.len());
|
|
if bom {
|
|
bytes.extend_from_slice(UTF8_BOM);
|
|
}
|
|
bytes.extend_from_slice(text.as_bytes());
|
|
write_atomic(path, &bytes)
|
|
}
|
|
|
|
/// Replaces the contents of `path` with `bytes` atomically.
|
|
///
|
|
/// The bytes go to a temporary file next to the target, which is flushed to
|
|
/// disk, given the target's permissions and renamed over it. Readers see
|
|
/// either the old or the new contents, never a mix. If `path` is a symbolic
|
|
/// link, the file it points to is replaced and the link kept. A new file is
|
|
/// created if `path` does not exist. File ownership is not carried over on
|
|
/// Unix (the new file belongs to the current user). If anything fails the
|
|
/// temporary file is removed; failing to remove it is ignored because the
|
|
/// write error is the one worth reporting.
|
|
///
|
|
/// # Errors
|
|
/// [`VfsError::NotAFile`] if `path` is a directory or has no file name,
|
|
/// [`VfsError::ReadOnly`] if the target is read-only, [`VfsError::Io`] (or
|
|
/// [`VfsError::NotFound`] for a missing parent directory) otherwise.
|
|
pub fn write_atomic(path: &Path, bytes: &[u8]) -> Result<(), VfsError> {
|
|
let target = match fs::symlink_metadata(path) {
|
|
Ok(meta) if meta.file_type().is_symlink() => {
|
|
fs::canonicalize(path).map_err(|err| VfsError::io(path, err))?
|
|
}
|
|
_ => path.to_path_buf(),
|
|
};
|
|
let existing = match fs::metadata(&target) {
|
|
Ok(meta) => Some(meta),
|
|
Err(err) if err.kind() == io::ErrorKind::NotFound => None,
|
|
Err(err) => return Err(VfsError::io(&target, err)),
|
|
};
|
|
if let Some(meta) = &existing {
|
|
if meta.is_dir() {
|
|
return Err(VfsError::NotAFile { path: target });
|
|
}
|
|
if meta.permissions().readonly() {
|
|
return Err(VfsError::ReadOnly { path: target });
|
|
}
|
|
}
|
|
let Some(name) = target.file_name() else {
|
|
return Err(VfsError::NotAFile { path: target });
|
|
};
|
|
let dir = match target.parent() {
|
|
Some(parent) if !parent.as_os_str().is_empty() => parent.to_path_buf(),
|
|
_ => PathBuf::from("."),
|
|
};
|
|
let (temp, mut file) = create_temp(&dir, name).map_err(|err| VfsError::io(&dir, err))?;
|
|
let result = (|| {
|
|
file.write_all(bytes)?;
|
|
if let Some(meta) = &existing {
|
|
fs::set_permissions(&temp, meta.permissions())?;
|
|
}
|
|
file.sync_all()?;
|
|
drop(file);
|
|
fs::rename(&temp, &target)
|
|
})();
|
|
if let Err(err) = result {
|
|
let _cleanup_failure_is_secondary = fs::remove_file(&temp);
|
|
return Err(VfsError::io(&target, err));
|
|
}
|
|
Ok(())
|
|
}
|
|
|
|
/// Creates a new, uniquely named hidden file in `dir` for writing `name`.
|
|
///
|
|
/// # Errors
|
|
/// The I/O error of the last attempt.
|
|
fn create_temp(dir: &Path, name: &std::ffi::OsStr) -> io::Result<(PathBuf, File)> {
|
|
let mut last = io::Error::new(io::ErrorKind::AlreadyExists, "no free temporary file name");
|
|
for _ in 0..TEMP_ATTEMPTS {
|
|
let serial = TEMP_COUNTER.fetch_add(1, Ordering::Relaxed);
|
|
let temp = dir.join(format!(
|
|
".{}.lutra-{}-{serial}.tmp",
|
|
name.to_string_lossy(),
|
|
std::process::id()
|
|
));
|
|
match OpenOptions::new().write(true).create_new(true).open(&temp) {
|
|
Ok(file) => return Ok((temp, file)),
|
|
Err(err) if err.kind() == io::ErrorKind::AlreadyExists => last = err,
|
|
Err(err) => return Err(err),
|
|
}
|
|
}
|
|
Err(last)
|
|
}
|