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

View file

@ -0,0 +1,283 @@
//! The open project: the VFS project, its watcher, and the translation of
//! changes on disk into engine events and buffer reloads.
//!
//! # Watched directories
//! The VFS watcher is non-recursive: the root is watched from the start and
//! [`Workspace::touch_dir`] adds each directory whose children a client
//! lists. To keep the cost bounded on huge trees (a deep `vendor/`), at most
//! [`MAX_WATCHED_DIRS_NATIVE`] directories besides the root are watched with
//! native notifications, and [`MAX_WATCHED_DIRS_POLLING`] when the watcher
//! fell back to polling, where every watched directory is rescanned each
//! interval. When the limit is reached the directory listed least recently
//! is unwatched; listing it again watches it again. Changes inside an
//! unwatched directory are not reported until then.
use std::collections::VecDeque;
use std::path::{Path, PathBuf};
use std::sync::mpsc::{Receiver, TryRecvError};
use lutra_text::Buffer;
use lutra_vfs::{Project, VfsError, VfsEvent, Watcher};
use crate::buffers::BufferId;
use crate::{EngineError, Event, State};
/// Directories watched besides the root with native notifications.
pub const MAX_WATCHED_DIRS_NATIVE: usize = 256;
/// Directories watched besides the root when polling.
pub const MAX_WATCHED_DIRS_POLLING: usize = 32;
/// Most VFS events handled by one pump; the rest wait for the next one.
pub const MAX_EVENTS_PER_PUMP: usize = 10_000;
/// An open project.
#[derive(Debug)]
pub struct Workspace {
/// The VFS project.
pub project: Project,
/// The watcher, `None` if watching is unavailable or failed.
watcher: Option<Watcher>,
/// Changes on disk from the watcher.
events: Option<Receiver<VfsEvent>>,
/// Directories watched besides the root, least recently listed first.
watched: VecDeque<PathBuf>,
}
impl Workspace {
/// Opens the folder at `path` and starts watching it. A watcher that
/// cannot start is not an error: the workspace works without it and the
/// returned events contain [`Event::WatchFailed`].
///
/// # Errors
/// [`EngineError::Failed`] if the folder cannot be opened.
pub fn open(path: &Path) -> Result<(Self, Vec<Event>), EngineError> {
let project = Project::open(path).map_err(vfs_error)?;
let root = project.root().to_path_buf();
let mut events = vec![Event::ProjectOpened {
root: root.to_string_lossy().into_owned(),
name: root
.file_name()
.map(|n| n.to_string_lossy().into_owned())
.unwrap_or_else(|| root.to_string_lossy().into_owned()),
}];
let (watcher, receiver) = match project.watch() {
Ok((watcher, receiver)) => (Some(watcher), Some(receiver)),
Err(e) => {
events.push(Event::WatchFailed {
message: e.to_string(),
});
(None, None)
}
};
Ok((
Self {
project,
watcher,
events: receiver,
watched: VecDeque::new(),
},
events,
))
}
/// Records that a client listed `dir` and watches it, unwatching the
/// least recently listed directory if the limit is reached. Watching is
/// best effort: a directory the watcher refuses or cannot read is simply
/// not watched, because listing it worked and that is what the caller
/// asked for.
pub fn touch_dir(&mut self, dir: &Path) {
let Some(watcher) = &self.watcher else {
return;
};
if dir.as_os_str().is_empty() {
return;
}
if let Some(at) = self.watched.iter().position(|d| d == dir) {
if let Some(d) = self.watched.remove(at) {
self.watched.push_back(d);
}
return;
}
if !matches!(watcher.watch_dir(dir), Ok(true)) {
return;
}
self.watched.push_back(dir.to_path_buf());
let limit = self.watch_limit();
let Some(watcher) = &self.watcher else {
return;
};
while self.watched.len() > limit {
if let Some(old) = self.watched.pop_front() {
watcher.unwatch_dir(&old);
}
}
}
/// How many directories besides the root may be watched with the
/// current backend; 0 without a watcher.
pub fn watch_limit(&self) -> usize {
match &self.watcher {
Some(w) if w.is_native() => MAX_WATCHED_DIRS_NATIVE,
Some(_) => MAX_WATCHED_DIRS_POLLING,
None => 0,
}
}
/// Directories watched besides the root, least recently listed first.
pub fn watched_dirs(&self) -> Vec<PathBuf> {
self.watched.iter().cloned().collect()
}
/// Whether the project is watched.
pub fn is_watching(&self) -> bool {
self.watcher.is_some()
}
/// Takes up to [`MAX_EVENTS_PER_PUMP`] pending changes from the watcher.
/// A failed or disconnected watcher is dropped and reported once.
fn drain(&mut self) -> (Vec<VfsEvent>, Option<String>) {
let mut out = Vec::new();
let mut failure = None;
let Some(receiver) = &self.events else {
return (out, None);
};
while out.len() < MAX_EVENTS_PER_PUMP {
match receiver.try_recv() {
Ok(VfsEvent::Failed(e)) => {
failure = Some(e.to_string());
break;
}
Ok(event) => out.push(event),
Err(TryRecvError::Empty) => break,
Err(TryRecvError::Disconnected) => {
failure = Some("the file watcher stopped".to_string());
break;
}
}
}
if failure.is_some() {
self.watcher = None;
self.events = None;
self.watched.clear();
}
(out, failure)
}
}
/// Applies pending changes on disk to the state: queues
/// [`Event::TreeChanged`] for affected directories, reloads clean buffers
/// whose file changed, and queues [`Event::FileChangedOnDisk`] for dirty
/// buffers and for buffers whose file disappeared.
pub fn pump(state: &mut State) {
let Some(workspace) = state.project.as_mut() else {
return;
};
let (changes, failure) = workspace.drain();
let root = workspace.project.root().to_path_buf();
let mut dirs: Vec<PathBuf> = Vec::new();
let mut add_dir = |path: &Path| {
let dir = path.parent().map(Path::to_path_buf).unwrap_or_default();
if !dirs.contains(&dir) {
dirs.push(dir);
}
};
let mut modified = Vec::new();
let mut gone = Vec::new();
for change in changes {
match change {
VfsEvent::Created { path, .. } => add_dir(&path),
VfsEvent::Removed { path } => {
add_dir(&path);
gone.push(path);
}
VfsEvent::Renamed { from, to } => {
add_dir(&from);
add_dir(&to);
gone.push(from);
}
VfsEvent::Modified { path } => modified.push(path),
VfsEvent::Failed(_) => {}
}
}
for dir in dirs {
state.emit(Event::TreeChanged {
dir: path_string(&dir),
});
}
for path in gone {
if let Some(id) = state.buffers.find(&path) {
state.emit(Event::FileChangedOnDisk {
path: path_string(&path),
id,
removed: true,
});
}
}
for path in modified {
if let Some(id) = state.buffers.find(&path) {
reload(state, id, &root.join(&path));
}
}
if let Some(message) = failure {
state.emit(Event::WatchFailed { message });
}
}
/// Brings buffer `id` in line with its file after the file changed: a clean
/// buffer takes the new text (unless it already matches, as after our own
/// save), a dirty one keeps its text and the client is told. A file that
/// cannot be read is reported like a removed one.
fn reload(state: &mut State, id: BufferId, abs: &Path) {
let Some(open) = state.buffers.get(id) else {
return;
};
let path = path_string(&open.path);
if open.dirty() {
state.emit(Event::FileChangedOnDisk {
path,
id,
removed: false,
});
return;
}
let file = match lutra_vfs::read_text(abs) {
Ok(file) => file,
Err(_) => {
state.emit(Event::FileChangedOnDisk {
path,
id,
removed: true,
});
return;
}
};
if file.text == open.buffer.save_text() && file.bom == open.bom {
return;
}
let Some(open) = state.buffers.get_mut(id) else {
return;
};
open.buffer = Buffer::new(&file.text);
open.bom = file.bom;
open.version = open.version.saturating_add(1);
open.saved_version = open.version;
let version = open.version;
state.emit(Event::BufferChanged { id, version });
}
/// A project-relative path as sent to clients: `/` separators, `""` for the
/// root.
pub fn path_string(path: &Path) -> String {
let text = path.to_string_lossy();
if std::path::MAIN_SEPARATOR == '/' {
text.into_owned()
} else {
text.replace(std::path::MAIN_SEPARATOR, "/")
}
}
/// Converts a VFS error into an engine error.
pub fn vfs_error(error: VfsError) -> EngineError {
EngineError::Failed(error.to_string())
}