//! Crash-recovery journal: unsaved buffers written to disk so a crash never //! loses the user's text. //! //! # Layout //! `/recovery//.json`, where the project id //! is the FNV-1a 64-bit hash of the canonical project root and the entry id //! the same hash of the project-relative path, both as 16 hex digits. FNV is //! used instead of `std`'s hasher because its output must stay the same //! across Rust versions. One file per dirty buffer holds an [`Entry`]: //! `{path, text, lineEnding, bom, savedAt}`; `text` is the buffer's text as //! held in memory, `savedAt` milliseconds since the Unix epoch. //! //! # When entries are written and removed //! - `buffer.edit` only records the time ([`mark_edited`]); nothing is //! written per keystroke. [`tick`], called from every //! [`crate::Engine::pump_vfs`], writes a buffer once it has been idle for //! [`IDLE`], or [`MAX_WAIT`] after its first unwritten edit during //! continuous typing. With the desktop's 100 ms pump an entry is on disk at //! most about 1.1 s after the last edit. //! - Writes go through [`lutra_vfs::write_atomic`], so an entry is either the //! old or the new version, never half written. //! - Saving, closing (also with `force`), `project.close`/`project.open` //! with `force` and `recovery.discard` remove entries ([`forget`]). Only //! entries this session wrote or restored are removed by save and close; //! entries left by a crashed session stay until they are restored or //! discarded. Editing such a file without restoring it overwrites its //! entry with the new text. //! //! # Untrusted input //! Entries are read with a size cap ([`MAX_ENTRY_BYTES`]), at most //! [`MAX_ENTRIES`] per project. An entry that cannot be read or parsed, or //! whose path escapes the project, is renamed to `.bad`, skipped and //! reported as a warning notification; it never stops the project from //! opening. use std::collections::{BTreeMap, BTreeSet}; use std::path::{Path, PathBuf}; use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH}; use serde::{Deserialize, Serialize}; use serde_json::{Map, Value}; use crate::buffers::{BufferId, LineEndingName}; use crate::workspace::path_string; use crate::{NotificationLevel, State}; /// A buffer is written after this long without an edit. pub const IDLE: Duration = Duration::from_millis(1000); /// A buffer edited continuously is written at least this often. pub const MAX_WAIT: Duration = Duration::from_millis(2000); /// Largest entry file read; larger ones count as corrupt. pub const MAX_ENTRY_BYTES: u64 = 512 * 1024 * 1024; /// Most entry files read per project. pub const MAX_ENTRIES: usize = 1000; /// Extension of entry files. const ENTRY_EXT: &str = "json"; /// Suffix appended to an entry that could not be read. const BAD_SUFFIX: &str = ".bad"; /// Catalog key of the warning for an unreadable entry. pub const KEY_CORRUPT: &str = "notification.recovery.corrupt"; /// Catalog key of the warning for a failed journal write. pub const KEY_WRITE_FAILED: &str = "notification.recovery.writeFailed"; /// Catalog key of the warning for an unreadable journal directory. pub const KEY_UNAVAILABLE: &str = "notification.recovery.unavailable"; /// One journal file: the unsaved text of one buffer. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct Entry { /// Project-relative path with `/` separators. pub path: String, /// The buffer's text as held in memory. pub text: String, /// The line ending the buffer saves with. pub line_ending: LineEndingName, /// The file has a UTF-8 byte order mark. pub bom: bool, /// When the entry was written, in milliseconds since the Unix epoch. pub saved_at: u64, } /// What `recoveryAvailable` and `recovery.list` report about an entry. #[derive(Debug, Clone, PartialEq, Eq, Serialize)] #[serde(rename_all = "camelCase")] pub struct EntryInfo { /// Project-relative path. pub path: String, /// When the entry was written, in milliseconds since the Unix epoch. pub saved_at: u64, /// The file was modified after the entry was written, or is gone. pub disk_changed: bool, } /// Edit times of a buffer whose latest text is not in the journal yet. #[derive(Debug, Clone, Copy)] struct Pending { /// The first edit since the last write. first: Instant, /// The latest edit. last: Instant, } impl Pending { /// Whether the buffer is due for writing at `now`: idle for [`IDLE`] or /// waiting for [`MAX_WAIT`]. fn due(&self, now: Instant) -> bool { now.saturating_duration_since(self.last) >= IDLE || now.saturating_duration_since(self.first) >= MAX_WAIT } } /// The journal of the open project. #[derive(Debug)] pub struct Journal { /// `/recovery/`; created on the first write. dir: PathBuf, /// Buffers with edits not written yet. pending: BTreeMap, /// Paths whose entry this session wrote or restored. owned: BTreeSet, /// A write failure was reported and no write has succeeded since. write_failed: bool, } impl Journal { /// The journal of the project at the canonical `root`, stored below /// `data_dir`. Touches nothing on disk. pub fn new(data_dir: &Path, root: &Path) -> Self { Self { dir: data_dir .join("recovery") .join(hex_hash(root.to_string_lossy().as_bytes())), pending: BTreeMap::new(), owned: BTreeSet::new(), write_failed: false, } } /// The directory holding the entries. pub fn dir(&self) -> &Path { &self.dir } /// The file of the entry for `path`. fn file(&self, path: &str) -> PathBuf { self.dir .join(format!("{}.{ENTRY_EXT}", hex_hash(path.as_bytes()))) } } /// FNV-1a 64-bit hash of `bytes` as 16 lowercase hex digits. pub fn hex_hash(bytes: &[u8]) -> String { let mut hash: u64 = 0xcbf2_9ce4_8422_2325; for byte in bytes { hash ^= u64::from(*byte); hash = hash.wrapping_mul(0x0000_0100_0000_01b3); } format!("{hash:016x}") } /// Milliseconds since the Unix epoch, 0 for a clock before it. fn millis(time: SystemTime) -> u64 { time.duration_since(UNIX_EPOCH) .map(|d| u64::try_from(d.as_millis()).unwrap_or(u64::MAX)) .unwrap_or(0) } /// Records an edit of buffer `id` at `now`; [`tick`] writes it later. pub fn mark_edited(state: &mut State, id: BufferId, now: Instant) { if let Some(journal) = state.journal.as_mut() { journal .pending .entry(id) .and_modify(|p| p.last = now) .or_insert(Pending { first: now, last: now, }); } } /// Writes every buffer that has been idle for [`IDLE`] or waiting for /// [`MAX_WAIT`] at `now`. pub fn tick(state: &mut State, now: Instant) { let Some(journal) = state.journal.as_ref() else { return; }; let due: Vec = journal .pending .iter() .filter(|(_, p)| p.due(now)) .map(|(id, _)| *id) .collect(); for id in due { write(state, id); } } /// Writes every buffer with unwritten edits now. pub fn flush(state: &mut State) { let ids: Vec = state .journal .as_ref() .map(|j| j.pending.keys().copied().collect()) .unwrap_or_default(); for id in ids { write(state, id); } } /// Writes the entry of buffer `id` if it is dirty. A failed write keeps the /// buffer pending, so the next tick tries again, and is reported once until /// a write succeeds. fn write(state: &mut State, id: BufferId) { let Some(open) = state.buffers.get(id) else { if let Some(journal) = state.journal.as_mut() { journal.pending.remove(&id); } return; }; if !open.dirty() { if let Some(journal) = state.journal.as_mut() { journal.pending.remove(&id); } return; } let entry = Entry { path: path_string(&open.path), text: open.buffer.text(), line_ending: LineEndingName::from(open.buffer.line_ending()), bom: open.bom, saved_at: millis(SystemTime::now()), }; let Some(journal) = state.journal.as_mut() else { return; }; let file = journal.file(&entry.path); let result = serde_json::to_vec(&entry) .map_err(|e| e.to_string()) .and_then(|bytes| { std::fs::create_dir_all(&journal.dir).map_err(|e| e.to_string())?; lutra_vfs::write_atomic(&file, &bytes).map_err(|e| e.to_string()) }); match result { Ok(()) => { journal.pending.remove(&id); journal.owned.insert(entry.path); journal.write_failed = false; } Err(reason) => { if journal.write_failed { return; } journal.write_failed = true; let mut params = Map::new(); params.insert("path".into(), Value::String(entry.path.clone())); params.insert("reason".into(), Value::String(reason.clone())); state.notify( NotificationLevel::Warning, Some(KEY_WRITE_FAILED), Some(format!( "Could not write the recovery copy of {}: {reason}", entry.path )), Some(params), ); } } } /// Drops the journal state of buffer `id` and removes its entry if this /// session owns it. Called when the buffer is saved or closed, before it is /// removed. A file that cannot be removed is left behind: it is offered /// again on the next open, which is safer than failing the save or close. pub fn forget(state: &mut State, id: BufferId) { let path = state.buffers.get(id).map(|b| path_string(&b.path)); let Some(journal) = state.journal.as_mut() else { return; }; journal.pending.remove(&id); let Some(path) = path else { return; }; if journal.owned.remove(&path) { let _ = std::fs::remove_file(journal.file(&path)); } } /// Reads every valid entry of the open project's journal, sorted by path. /// Unreadable entries are renamed to `.bad` and reported as warning /// notifications. A missing journal directory means no entries. pub fn scan(state: &mut State) -> Vec { let Some(journal) = state.journal.as_ref() else { return Vec::new(); }; let dir = journal.dir.clone(); let listing = match std::fs::read_dir(&dir) { Ok(listing) => listing, Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Vec::new(), Err(e) => { let mut params = Map::new(); params.insert("reason".into(), Value::String(e.to_string())); state.notify( NotificationLevel::Warning, Some(KEY_UNAVAILABLE), Some(format!("Could not read the recovery journal: {e}")), Some(params), ); return Vec::new(); } }; let mut files: Vec = listing .filter_map(Result::ok) .map(|e| e.path()) .filter(|p| p.extension().is_some_and(|ext| ext == ENTRY_EXT) && p.is_file()) .collect(); files.sort(); files.truncate(MAX_ENTRIES); let mut entries = Vec::new(); for file in files { match read_entry(state, &file) { Ok(entry) => entries.push(entry), Err(reason) => quarantine(state, &file, &reason), } } entries.sort_by(|a, b| a.path.cmp(&b.path)); entries.dedup_by(|a, b| a.path == b.path); entries } /// Reads and checks one entry file. /// /// # Errors /// A description of why the entry is unusable. fn read_entry(state: &State, file: &Path) -> Result { let bytes = lutra_vfs::read_bytes(file, MAX_ENTRY_BYTES).map_err(|e| e.to_string())?; let entry: Entry = serde_json::from_slice(&bytes).map_err(|e| e.to_string())?; if entry.path.is_empty() { return Err("empty path".into()); } let journal = state.journal.as_ref().ok_or("no journal")?; if journal.file(&entry.path).file_name() != file.file_name() { return Err("the file name does not match the path".into()); } let workspace = state.project.as_ref().ok_or("no project")?; workspace .project .resolve(Path::new(&entry.path)) .map_err(|e| e.to_string())?; Ok(entry) } /// Moves an unusable entry aside and reports it. The text inside may still /// be worth something to the user, so it is renamed, not deleted. fn quarantine(state: &mut State, file: &Path, reason: &str) { let mut bad = file.as_os_str().to_os_string(); bad.push(BAD_SUFFIX); let _ = std::fs::rename(file, PathBuf::from(&bad)); let name = file .file_name() .map(|n| n.to_string_lossy().into_owned()) .unwrap_or_default(); let mut params = Map::new(); params.insert("file".into(), Value::String(name.clone())); params.insert("reason".into(), Value::String(reason.to_string())); state.notify( NotificationLevel::Warning, Some(KEY_CORRUPT), Some(format!( "Skipped an unreadable recovery entry {name}: {reason}" )), Some(params), ); } /// What clients see about `entry`: whether the file changed on disk after /// the entry was written (or is gone) is judged by its modification time. pub fn info(state: &State, entry: &Entry) -> EntryInfo { let disk_changed = state .project .as_ref() .and_then(|w| w.project.resolve(Path::new(&entry.path)).ok()) .and_then(|abs| std::fs::metadata(abs).ok()) .and_then(|meta| meta.modified().ok()) .is_none_or(|modified| millis(modified) > entry.saved_at); EntryInfo { path: entry.path.clone(), saved_at: entry.saved_at, disk_changed, } } /// Marks `path` as written by this session, so save and close remove it. pub fn adopt(state: &mut State, path: &str) { if let Some(journal) = state.journal.as_mut() { journal.owned.insert(path.to_string()); } } /// Removes the entry for `path`. Returns whether a file was removed. pub fn remove(state: &mut State, path: &str) -> bool { let Some(journal) = state.journal.as_mut() else { return false; }; journal.owned.remove(path); std::fs::remove_file(journal.file(path)).is_ok() } #[cfg(test)] mod tests { use super::*; #[test] fn hashes_are_stable() { assert_eq!(hex_hash(b""), "cbf29ce484222325"); assert_eq!(hex_hash(b"a"), "af63dc4c8601ec8c"); assert_eq!(hex_hash(b"src/a.php").len(), 16); } #[test] fn entries_serialise_in_camel_case() { let entry = Entry { path: "a.php".into(), text: "x\r\n".into(), line_ending: LineEndingName::Crlf, bom: true, saved_at: 5, }; assert_eq!( serde_json::to_value(&entry).unwrap(), serde_json::json!({"path": "a.php", "text": "x\r\n", "lineEnding": "crlf", "bom": true, "savedAt": 5}) ); } #[test] fn due_after_idle_or_max_wait() { let start = Instant::now(); let typing = Pending { first: start, last: start + Duration::from_millis(1500), }; assert!(!typing.due(start + Duration::from_millis(1900))); assert!(typing.due(start + MAX_WAIT)); let once = Pending { first: start, last: start, }; assert!(!once.due(start + Duration::from_millis(999))); assert!(once.due(start + IDLE)); assert!(!once.due(start)); } }