Lutra/crates/vfs/src/io.rs
danny 5d49b57b9c M1.2: vfs with ignore rules, polling watcher and safe file IO
- 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>
2026-10-14 19:24:02 +02:00

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)
}