Lutra/crates/engine/src/journal.rs
danny 0b40eb90f8 M1.7: crash-recovery journal and restore dialog
Dirty buffers are written atomically to <data_dir>/recovery/<project-id>/
about 1 s after the last edit (at most 2 s while typing), from pump_vfs,
never per keystroke. Entries are removed on save, close (also force),
forced project close/open and recovery.discard. project.open emits
recoveryAvailable; recovery.list/restore/discard; restored buffers are
dirty and keep line ending and BOM. Corrupt entries are moved aside and
reported as warning notifications.

UI: restore dialog in ui/src/components/recovery (Restore all, Restore
selected, Discard, time, changed-on-disk hint), catalog keys and runtime
allow-list. Tests: crash/restore with CRLF + BOM, corrupt entries, removal
paths, property test of random edits, headless control-channel test,
Vitest for the dialog. Docs: architecture, parity, gaps, ROADMAP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 15:56:41 +02:00

460 lines
16 KiB
Rust

//! Crash-recovery journal: unsaved buffers written to disk so a crash never
//! loses the user's text.
//!
//! # Layout
//! `<data_dir>/recovery/<project-id>/<entry-id>.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 `<entry>.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 {
/// `<data_dir>/recovery/<project-id>`; created on the first write.
dir: PathBuf,
/// Buffers with edits not written yet.
pending: BTreeMap<BufferId, Pending>,
/// Paths whose entry this session wrote or restored.
owned: BTreeSet<String>,
/// 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<BufferId> = 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<BufferId> = 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 `<entry>.bad` and reported as warning
/// notifications. A missing journal directory means no entries.
pub fn scan(state: &mut State) -> Vec<Entry> {
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<PathBuf> = 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<Entry, String> {
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));
}
}