//! 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, 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 { 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 { 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) -> Result { 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) }