Lutra/crates/control/src/backend.rs
danny f1976c7d67 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>
2026-10-14 20:24:44 +02:00

114 lines
3.6 KiB
Rust

//! The interface the control channel needs from its host, and the
//! subscriber list hosts use to publish engine events.
use std::path::Path;
use std::sync::mpsc::{SyncSender, TrySendError};
use std::sync::{Mutex, PoisonError};
use lutra_engine::{CommandInfo, EngineError, Event};
use serde_json::Value;
/// Queue of events for one subscriber. Bounded so that a client that stops
/// reading cannot make the host buffer without limit.
pub type EventSink = SyncSender<Event>;
/// Capacity of each subscriber's queue.
pub const EVENT_QUEUE: usize = 4096;
/// What the control channel can ask the host to do.
///
/// The desktop app implements it on top of its engine and window; tests
/// implement it with a bare engine. Methods are called from connection
/// threads, so implementations synchronise internally.
pub trait Backend: Send + Sync + 'static {
/// Runs an engine command, applies its effects and publishes its events.
///
/// # Errors
/// The engine's error for the command.
fn execute(&self, command: &str, params: Value) -> Result<Value, EngineError>;
/// Lists every command with its current enabled state.
fn list_commands(&self) -> Vec<CommandInfo>;
/// Writes a PNG screenshot of the main window to `path`.
///
/// # Errors
/// A message if there is no window to capture or the file cannot be
/// written.
fn screenshot(&self, path: &Path) -> Result<(), String>;
/// Adds a subscriber that receives every engine event from now on.
fn subscribe(&self, sink: EventSink);
}
/// The event subscribers of a host.
#[derive(Debug, Default)]
pub struct Subscribers {
/// Live subscribers.
sinks: Mutex<Vec<EventSink>>,
}
impl Subscribers {
/// Adds a subscriber.
pub fn add(&self, sink: EventSink) {
self.sinks
.lock()
.unwrap_or_else(PoisonError::into_inner)
.push(sink);
}
/// Sends `events` to every subscriber, in order. A subscriber whose
/// queue is full or whose receiver is gone is dropped: a full queue
/// means the client stopped reading, and dropping it keeps the host from
/// blocking or buffering without limit.
pub fn publish(&self, events: &[Event]) {
if events.is_empty() {
return;
}
let mut sinks = self.sinks.lock().unwrap_or_else(PoisonError::into_inner);
sinks.retain(|sink| {
events
.iter()
.all(|event| match sink.try_send(event.clone()) {
Ok(()) => true,
Err(TrySendError::Full(_) | TrySendError::Disconnected(_)) => false,
})
});
}
/// Number of live subscribers.
pub fn len(&self) -> usize {
self.sinks
.lock()
.unwrap_or_else(PoisonError::into_inner)
.len()
}
/// Whether there is no subscriber.
pub fn is_empty(&self) -> bool {
self.len() == 0
}
}
#[cfg(test)]
mod tests {
use std::sync::mpsc::sync_channel;
use super::*;
#[test]
fn publishes_in_order_and_drops_dead_or_slow_subscribers() {
let subs = Subscribers::default();
let (fast_tx, fast_rx) = sync_channel(10);
let (slow_tx, _slow_rx) = sync_channel(1);
let (dead_tx, dead_rx) = sync_channel(10);
subs.add(fast_tx);
subs.add(slow_tx);
subs.add(dead_tx);
drop(dead_rx);
subs.publish(&[Event::ProjectClosed, Event::BufferClosed { id: 1 }]);
assert_eq!(subs.len(), 1);
assert_eq!(fast_rx.try_recv().unwrap(), Event::ProjectClosed);
assert_eq!(fast_rx.try_recv().unwrap(), Event::BufferClosed { id: 1 });
}
}