Lutra/crates/engine/tests/recovery.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

497 lines
17 KiB
Rust

//! Crash-recovery journal: unsaved text survives dropping the engine and is
//! restored exactly by a new engine on the same directories.
#![allow(
clippy::unwrap_used,
clippy::expect_used,
clippy::indexing_slicing,
clippy::panic
)]
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};
use lutra_engine::{Engine, EngineConfig, Event, journal};
use proptest::prelude::*;
use serde_json::{Value, json};
use tempfile::TempDir;
/// A project folder and engine directories that outlive the engines.
struct Setup {
/// Holds everything.
_tmp: TempDir,
/// The project root.
project: PathBuf,
/// The engine directories.
config: EngineConfig,
}
impl Setup {
fn new(files: &[(&str, &[u8])]) -> Self {
let tmp = tempfile::tempdir().unwrap();
let project = tmp.path().join("project");
std::fs::create_dir(&project).unwrap();
for (name, bytes) in files {
let path = project.join(name);
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(path, bytes).unwrap();
}
let config = EngineConfig {
config_dir: tmp.path().join("config"),
data_dir: tmp.path().join("data"),
};
Self {
_tmp: tmp,
project,
config,
}
}
/// A fresh engine with the project open, and the events of opening it.
fn engine(&self) -> (Engine, Vec<Event>) {
let mut engine = Engine::with_config(self.config.clone()).unwrap();
engine.take_events();
let out = engine
.execute("project.open", json!({"path": self.project}))
.unwrap();
(engine, out.events)
}
/// The journal directory of the project.
fn journal_dir(&self) -> PathBuf {
let root = std::fs::canonicalize(&self.project).unwrap();
let (engine, _) = self.engine();
let dir = engine.state().journal.as_ref().unwrap().dir().to_path_buf();
assert!(dir.starts_with(self.config.data_dir.join("recovery")));
assert!(!root.as_os_str().is_empty());
dir
}
/// The entry files in the journal directory.
fn entry_files(&self) -> Vec<PathBuf> {
let Ok(listing) = std::fs::read_dir(self.journal_dir()) else {
return Vec::new();
};
let mut files: Vec<PathBuf> = listing
.map(|e| e.unwrap().path())
.filter(|p| p.extension().is_some_and(|e| e == "json"))
.collect();
files.sort();
files
}
}
fn run(engine: &mut Engine, command: &str, params: Value) -> Value {
engine
.execute(command, params)
.unwrap_or_else(|e| panic!("{command}: {e}"))
.value
}
fn open(engine: &mut Engine, path: &str) -> u64 {
run(engine, "file.open", json!({"path": path}))["id"]
.as_u64()
.unwrap()
}
fn edit(engine: &mut Engine, id: u64, from: usize, to: usize, insert: &str) {
let version = run(engine, "buffer.get", json!({"id": id}))["version"].clone();
run(
engine,
"buffer.edit",
json!({"id": id, "baseVersion": version, "edits": [{"from": from, "to": to, "insert": insert}]}),
);
}
fn recovery_entries(events: &[Event]) -> Option<Vec<Value>> {
events.iter().find_map(|e| match e {
Event::RecoveryAvailable { entries } => {
Some(serde_json::to_value(entries).unwrap().as_array()?.clone())
}
_ => None,
})
}
#[test]
fn a_dropped_engine_leaves_text_that_a_new_engine_restores_exactly() {
let original = b"\xEF\xBB\xBF<?php\r\necho 1;\r\n";
let setup = Setup::new(&[("src/a.php", original)]);
let (mut engine, events) = setup.engine();
assert!(
recovery_entries(&events).is_none(),
"nothing to recover yet"
);
let id = open(&mut engine, "src/a.php");
edit(&mut engine, id, 7, 7, "$x = 'ü';\r\n");
let expected = run(&mut engine, "buffer.get", json!({"id": id}))["text"].clone();
assert_eq!(expected, "<?php\r\n$x = 'ü';\r\necho 1;\r\n");
engine.pump_vfs().unwrap();
assert!(setup.entry_files().is_empty(), "not written per keystroke");
let deadline = Instant::now() + Duration::from_secs(5);
while setup.entry_files().is_empty() {
assert!(Instant::now() < deadline, "journal not written within 5 s");
std::thread::sleep(Duration::from_millis(100));
engine.pump_vfs().unwrap();
}
drop(engine);
assert_eq!(
std::fs::read(setup.project.join("src/a.php")).unwrap(),
original,
"the file itself is untouched"
);
let (mut engine, events) = setup.engine();
let entries = recovery_entries(&events).expect("recoveryAvailable after project.open");
assert_eq!(entries.len(), 1);
assert_eq!(entries[0]["path"], "src/a.php");
assert_eq!(entries[0]["diskChanged"], false);
assert!(entries[0]["savedAt"].as_u64().unwrap() > 0);
assert_eq!(
run(&mut engine, "recovery.list", Value::Null)["entries"],
Value::Array(entries)
);
let out = engine
.execute("recovery.restore", json!({"paths": ["src/a.php"]}))
.unwrap();
assert_eq!(out.value["failed"], json!([]));
let id = out.value["restored"][0]["id"].as_u64().unwrap();
assert!(
out.events
.contains(&Event::DirtyChanged { id, dirty: true })
);
let got = run(&mut engine, "buffer.get", json!({"id": id}));
assert_eq!(got["text"], expected);
assert_eq!(got["lineEnding"], "crlf");
assert_eq!(got["dirty"], true);
assert!(engine.state().buffers.get(id).unwrap().bom);
run(&mut engine, "file.save", json!({"id": id}));
assert_eq!(
std::fs::read(setup.project.join("src/a.php")).unwrap(),
"\u{feff}<?php\r\n$x = 'ü';\r\necho 1;\r\n".as_bytes()
);
assert!(setup.entry_files().is_empty(), "saving removes the entry");
}
#[test]
fn close_force_discard_and_project_close_remove_entries() {
let setup = Setup::new(&[("a.php", b"a"), ("b.php", b"b"), ("c.php", b"c")]);
let (mut engine, _) = setup.engine();
let a = open(&mut engine, "a.php");
let b = open(&mut engine, "b.php");
let c = open(&mut engine, "c.php");
for id in [a, b, c] {
edit(&mut engine, id, 0, 0, "x");
}
engine.flush_journal().unwrap();
assert_eq!(setup.entry_files().len(), 3);
run(&mut engine, "buffer.close", json!({"id": a, "force": true}));
assert_eq!(setup.entry_files().len(), 2);
let out = run(&mut engine, "recovery.discard", json!({"paths": ["b.php"]}));
assert_eq!(out["discarded"], json!(["b.php"]));
assert_eq!(setup.entry_files().len(), 1);
engine.flush_journal().unwrap();
assert_eq!(
setup.entry_files().len(),
2,
"a discarded entry of a dirty open buffer is journaled again"
);
run(&mut engine, "project.close", json!({"force": true}));
assert!(setup.entry_files().is_empty());
assert!(engine.state().journal.is_none());
}
#[test]
fn entries_of_a_crashed_session_survive_until_restored_or_discarded() {
let setup = Setup::new(&[("a.php", b"a"), ("b.php", b"b")]);
let (mut engine, _) = setup.engine();
for path in ["a.php", "b.php"] {
let id = open(&mut engine, path);
edit(&mut engine, id, 1, 1, "!");
}
engine.flush_journal().unwrap();
drop(engine);
let (mut engine, events) = setup.engine();
assert_eq!(recovery_entries(&events).unwrap().len(), 2);
let id = open(&mut engine, "a.php");
run(&mut engine, "buffer.close", json!({"id": id}));
assert_eq!(
setup.entry_files().len(),
2,
"closing a clean buffer keeps the old entry"
);
let out = run(&mut engine, "recovery.discard", Value::Null);
assert_eq!(out["discarded"], json!(["a.php", "b.php"]));
assert!(setup.entry_files().is_empty());
assert_eq!(
run(&mut engine, "recovery.list", Value::Null)["entries"],
json!([])
);
}
#[test]
fn restore_reports_missing_entries_and_newer_unsaved_buffers() {
let setup = Setup::new(&[("a.php", b"a"), ("b.php", b"b")]);
let (mut engine, _) = setup.engine();
for path in ["a.php", "b.php"] {
let id = open(&mut engine, path);
edit(&mut engine, id, 1, 1, "1");
}
engine.flush_journal().unwrap();
drop(engine);
let (mut engine, _) = setup.engine();
let a = open(&mut engine, "a.php");
let b = open(&mut engine, "b.php");
edit(&mut engine, b, 0, 0, "newer");
let out = run(
&mut engine,
"recovery.restore",
json!({"paths": ["a.php", "b.php", "nope.php"]}),
);
assert_eq!(out["restored"], json!([{"path": "a.php", "id": a}]));
let failed: Vec<&str> = out["failed"]
.as_array()
.unwrap()
.iter()
.map(|f| f["path"].as_str().unwrap())
.collect();
assert_eq!(failed, vec!["nope.php", "b.php"]);
assert_eq!(
run(&mut engine, "buffer.get", json!({"id": a}))["text"],
"a1"
);
assert_eq!(
run(&mut engine, "buffer.get", json!({"id": b}))["text"],
"newerb"
);
}
#[test]
fn disk_changes_after_the_entry_are_flagged() {
let setup = Setup::new(&[("a.php", b"a"), ("gone.php", b"g")]);
let (mut engine, _) = setup.engine();
for path in ["a.php", "gone.php"] {
let id = open(&mut engine, path);
edit(&mut engine, id, 0, 0, "x");
}
engine.flush_journal().unwrap();
drop(engine);
std::thread::sleep(Duration::from_millis(50));
std::fs::write(setup.project.join("a.php"), "changed").unwrap();
std::fs::remove_file(setup.project.join("gone.php")).unwrap();
let (mut engine, events) = setup.engine();
let entries = recovery_entries(&events).unwrap();
assert_eq!(entries[0]["path"], "a.php");
assert_eq!(entries[0]["diskChanged"], true);
assert_eq!(entries[1]["path"], "gone.php");
assert_eq!(entries[1]["diskChanged"], true);
let out = run(&mut engine, "recovery.restore", Value::Null);
assert_eq!(out["restored"].as_array().unwrap().len(), 2);
let gone = out["restored"][1]["id"].as_u64().unwrap();
assert_eq!(
run(&mut engine, "buffer.get", json!({"id": gone}))["text"],
"xg"
);
run(&mut engine, "file.save", json!({"id": gone}));
assert_eq!(
std::fs::read_to_string(setup.project.join("gone.php")).unwrap(),
"xg"
);
}
#[test]
fn corrupt_entries_are_skipped_with_a_warning() {
let setup = Setup::new(&[("a.php", b"a")]);
let (mut engine, _) = setup.engine();
let id = open(&mut engine, "a.php");
edit(&mut engine, id, 0, 0, "ok ");
engine.flush_journal().unwrap();
drop(engine);
let dir = setup.journal_dir();
let bad_cases: [(&str, &[u8]); 4] = [
("0000000000000001.json", b"{not json"),
("0000000000000002.json", b"\xff\xfe\x00"),
(
"0000000000000003.json",
br#"{"path":"../evil.php","text":"x","lineEnding":"lf","bom":false,"savedAt":1}"#,
),
(
"0000000000000004.json",
br#"{"path":"a.php","text":"x","lineEnding":"lf","bom":false,"savedAt":1}"#,
),
];
for (name, bytes) in bad_cases {
std::fs::write(dir.join(name), bytes).unwrap();
}
let (mut engine, events) = setup.engine();
let entries = recovery_entries(&events).unwrap();
assert_eq!(entries.len(), 1, "only the good entry: {entries:?}");
assert_eq!(entries[0]["path"], "a.php");
let warnings: Vec<&Event> = events
.iter()
.filter(|e| matches!(e, Event::Notification { message_key: Some(k), .. } if k == journal::KEY_CORRUPT))
.collect();
assert_eq!(warnings.len(), 4);
for (name, _) in bad_cases {
assert!(
dir.join(format!("{name}.bad")).is_file(),
"{name} kept aside"
);
assert!(!dir.join(name).exists());
}
let out = run(&mut engine, "recovery.restore", Value::Null);
let id = out["restored"][0]["id"].as_u64().unwrap();
assert_eq!(
run(&mut engine, "buffer.get", json!({"id": id}))["text"],
"ok a"
);
assert!(
engine.take_events().iter().all(
|e| !matches!(e, Event::Notification { message_key: Some(k), .. } if k == journal::KEY_CORRUPT)
),
"reported once"
);
}
#[test]
fn an_engine_without_persistence_has_no_journal() {
let setup = Setup::new(&[("a.php", b"a")]);
let mut engine = Engine::new().unwrap();
run(&mut engine, "project.open", json!({"path": setup.project}));
let id = open(&mut engine, "a.php");
edit(&mut engine, id, 0, 0, "x");
engine.flush_journal().unwrap();
assert!(engine.state().journal.is_none());
assert_eq!(
run(&mut engine, "recovery.list", Value::Null)["entries"],
json!([])
);
assert!(!setup.config.data_dir.exists());
}
#[test]
fn an_unwritable_journal_warns_once_and_keeps_editing() {
let setup = Setup::new(&[("a.php", b"a")]);
std::fs::create_dir_all(&setup.config.data_dir).unwrap();
std::fs::write(setup.config.data_dir.join("recovery"), "a file").unwrap();
let (mut engine, _) = setup.engine();
let id = open(&mut engine, "a.php");
edit(&mut engine, id, 0, 0, "x");
let events = engine.flush_journal().unwrap();
assert!(events.iter().any(|e| matches!(
e,
Event::Notification { message_key: Some(k), .. } if k == journal::KEY_WRITE_FAILED
)));
edit(&mut engine, id, 0, 0, "y");
assert!(engine.flush_journal().unwrap().is_empty(), "warned once");
assert_eq!(
run(&mut engine, "buffer.get", json!({"id": id}))["text"],
"yxa"
);
}
#[test]
fn journal_write_cost_for_a_one_megabyte_buffer() {
let line = "$value = str_repeat('lutra', 10); // äöü\n";
let text = line.repeat(1024 * 1024 / line.len() + 1);
let setup = Setup::new(&[("big.php", text.as_bytes())]);
let (mut engine, _) = setup.engine();
let id = open(&mut engine, "big.php");
let mut samples = Vec::new();
for i in 0..10 {
edit(&mut engine, id, 0, 0, &i.to_string());
let start = Instant::now();
engine.flush_journal().unwrap();
samples.push(start.elapsed());
}
samples.sort();
let median = samples[samples.len() / 2];
eprintln!(
"journal write of {} bytes: median {:?}, min {:?}, max {:?}",
text.len(),
median,
samples[0],
samples[samples.len() - 1]
);
assert!(median < Duration::from_millis(500), "median {median:?}");
let size = std::fs::metadata(&setup.entry_files()[0]).unwrap().len();
assert!(size > 1024 * 1024);
}
/// One random edit: where (as a fraction of the text), how much to delete,
/// and what to insert.
fn edit_strategy() -> impl Strategy<Value = (f64, usize, String)> {
(
0.0..=1.0f64,
0usize..6,
prop::string::string_regex("(a|ü|😀|\r\n|\n|\r| |x){0,6}").unwrap(),
)
}
/// Applies random edits through `buffer.edit`; edits whose offsets fall
/// inside a character or a CRLF are rejected by the engine and skipped.
fn apply_random(engine: &mut Engine, id: u64, edits: &[(f64, usize, String)]) {
for (at, del, insert) in edits {
let got = run(engine, "buffer.get", json!({"id": id}));
let len = got["text"].as_str().unwrap().encode_utf16().count();
let from = ((len as f64) * at) as usize;
let to = (from + del).min(len);
let _ = engine.execute(
"buffer.edit",
json!({"id": id, "baseVersion": got["version"], "edits": [{"from": from, "to": to, "insert": insert}]}),
);
}
}
proptest! {
#![proptest_config(ProptestConfig::with_cases(24))]
#[test]
fn random_edits_then_crash_restore_the_buffer(
crlf in any::<bool>(),
bom in any::<bool>(),
edits in prop::collection::vec(edit_strategy(), 1..20),
more in prop::collection::vec(edit_strategy(), 0..5),
) {
let ending = if crlf { "\r\n" } else { "\n" };
let mut bytes = Vec::new();
if bom {
bytes.extend_from_slice(b"\xEF\xBB\xBF");
}
bytes.extend_from_slice(format!("<?php{ending}echo 1;{ending}").as_bytes());
let setup = Setup::new(&[("a.php", &bytes)]);
let (mut engine, _) = setup.engine();
let id = open(&mut engine, "a.php");
apply_random(&mut engine, id, &edits);
engine.flush_journal().unwrap();
let before = engine.state().buffers.get(id).unwrap().clone();
apply_random(&mut engine, id, &more);
drop(engine);
let (mut engine, events) = setup.engine();
let offered = recovery_entries(&events).is_some();
prop_assert_eq!(offered, before.dirty());
if !offered {
return Ok(());
}
let out = run(&mut engine, "recovery.restore", Value::Null);
let rid = out["restored"][0]["id"].as_u64().unwrap();
let after = engine.state().buffers.get(rid).unwrap();
prop_assert_eq!(after.buffer.text(), before.buffer.text());
prop_assert_eq!(after.buffer.line_ending(), before.buffer.line_ending());
prop_assert_eq!(after.buffer.save_text(), before.buffer.save_text());
prop_assert_eq!(after.bom, before.bom);
prop_assert!(after.dirty());
prop_assert!(Path::new(&setup.project).join("a.php").is_file());
}
}