M1.3: engine workspace, file and buffer commands, event stream

State holds the open project (VFS project, watcher, watched directories)
and versioned buffers. New commands: project.open/close/children,
file.open/save/saveAll, buffer.get/edit/close. buffer.edit takes UTF-16
change sets based on a version and fails with the new stale_version code;
closing dirty buffers or projects without force fails with
unsaved_changes. Commands queue events (projectOpened, treeChanged,
bufferChanged, dirtyChanged, fileChangedOnDisk, ...) that the engine
returns in Outcome.events; Engine::pump_vfs maps changes on disk to
events and reloads clean buffers. project.children watches listed
directories, capped at 256 native / 32 polling, least recently listed
dropped first.

Control channel: events.subscribe streams {"event": ...} lines, with
bounded per-subscriber queues (lutra_control::Subscribers) and method docs
in methods.rs. testkit's EngineBackend and the desktop Host implement the
new Backend::subscribe. Verified with 14 engine integration tests, a TCP
events test and the running app over the control channel.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-14 20:24:44 +02:00
parent a63ab4ac45
commit f1976c7d67
30 changed files with 2235 additions and 46 deletions

103
crates/engine/src/event.rs Normal file
View file

@ -0,0 +1,103 @@
//! Events: state changes the engine pushes to its hosts.
//!
//! Commands and [`crate::Engine::pump_vfs`] queue events in the state; the
//! engine hands them to the host with each [`crate::Outcome`] and from each
//! pump. Hosts fan them out to the frontend (Tauri events) and to control
//! channel subscribers (`events.subscribe`). Events describe what changed;
//! consumers fetch data they need with commands (`project.children`,
//! `buffer.get`).
//!
//! Serialised as `{"kind": "<camelCase variant>", ...fields in camelCase}`.
//! Paths are project-relative with `/` separators, the root is `""`.
use serde::Serialize;
/// A state change.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(
tag = "kind",
rename_all = "camelCase",
rename_all_fields = "camelCase"
)]
pub enum Event {
/// A project was opened.
ProjectOpened {
/// Absolute root path.
root: String,
/// Folder name, for titles.
name: String,
},
/// The project was closed; all buffers are gone.
ProjectClosed,
/// The children of a directory changed on disk; refetch them with
/// `project.children`.
TreeChanged {
/// The directory.
dir: String,
},
/// A buffer was opened.
BufferOpened {
/// Buffer id.
id: u64,
/// File path.
path: String,
},
/// A buffer's text changed; `version` is the new version.
BufferChanged {
/// Buffer id.
id: u64,
/// New version.
version: u64,
},
/// A buffer became dirty or clean.
DirtyChanged {
/// Buffer id.
id: u64,
/// Whether it has unsaved changes.
dirty: bool,
},
/// A buffer was closed.
BufferClosed {
/// Buffer id.
id: u64,
},
/// The file of an open buffer changed or disappeared on disk and the
/// buffer kept its text: it is dirty, or the file is gone.
FileChangedOnDisk {
/// File path.
path: String,
/// The open buffer.
id: u64,
/// The file was removed or renamed away.
removed: bool,
},
/// File watching stopped; the project keeps working without it.
WatchFailed {
/// Why.
message: String,
},
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::Event;
#[test]
fn serialises_with_kind_and_camel_case_fields() {
let e = Event::FileChangedOnDisk {
path: "src/a.php".into(),
id: 3,
removed: false,
};
assert_eq!(
serde_json::to_value(e).unwrap(),
json!({"kind": "fileChangedOnDisk", "path": "src/a.php", "id": 3, "removed": false})
);
assert_eq!(
serde_json::to_value(Event::ProjectClosed).unwrap(),
json!({"kind": "projectClosed"})
);
}
}