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

@ -1,17 +1,27 @@
//! The interface the control channel needs from its host.
//! 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};
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 and applies its effects.
/// Runs an engine command, applies its effects and publishes its events.
///
/// # Errors
/// The engine's error for the command.
@ -26,4 +36,79 @@ pub trait Backend: Send + Sync + 'static {
/// 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 });
}
}

View file

@ -3,12 +3,14 @@
//! Serves JSON lines on `127.0.0.1:PORT` so that scripts and agents can run
//! engine commands and inspect the user interface. The protocol is described
//! in docs/architecture.md › Control channel; [`protocol`] parses and answers
//! single lines, [`server`] owns the sockets. Hosts plug in through
//! [`Backend`].
//! single lines, [`server`] owns the sockets, [`methods`] lists the
//! methods. Hosts plug in through [`Backend`] and publish engine events to
//! subscribed connections through [`Subscribers`].
mod backend;
pub mod methods;
pub mod protocol;
pub mod server;
pub use backend::Backend;
pub use backend::{Backend, EVENT_QUEUE, EventSink, Subscribers};
pub use server::{ServerHandle, start};

View file

@ -0,0 +1,57 @@
//! The methods of the control channel: names and documentation.
//!
//! Every request is `{"id", "method", "params"}` and gets one response line
//! (see [`crate::protocol`]). After `events.subscribe` the connection also
//! receives event lines `{"event": {...}}` between responses; each line is
//! written whole, so lines never interleave.
/// `app.ping`: liveness check.
pub const APP_PING: &str = "app.ping";
/// `engine.execute`: runs an engine command.
pub const ENGINE_EXECUTE: &str = "engine.execute";
/// `engine.listCommands`: lists the engine's commands.
pub const ENGINE_LIST_COMMANDS: &str = "engine.listCommands";
/// `ui.screenshot`: writes a PNG of the main window.
pub const UI_SCREENSHOT: &str = "ui.screenshot";
/// `events.subscribe`: streams engine events on this connection.
pub const EVENTS_SUBSCRIBE: &str = "events.subscribe";
/// Documentation of one method.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MethodDoc {
/// Method name.
pub name: &'static str,
/// Params.
pub params: &'static str,
/// Result.
pub result: &'static str,
}
/// Every method, for help output and agents.
pub const METHODS: &[MethodDoc] = &[
MethodDoc {
name: APP_PING,
params: "none",
result: "{ pong: true, version }",
},
MethodDoc {
name: ENGINE_EXECUTE,
params: "{ command: string, params?: object }",
result: "the command's result; errors carry the engine's code (unknown_command, disabled, invalid_params, stale_version, unsaved_changes, failed, internal)",
},
MethodDoc {
name: ENGINE_LIST_COMMANDS,
params: "none",
result: "[{ id, label, menuPath, defaultShortcut, params, enabled }]",
},
MethodDoc {
name: UI_SCREENSHOT,
params: "{ path: string }",
result: "{ path }; error screenshot_failed if the window cannot be captured",
},
MethodDoc {
name: EVENTS_SUBSCRIBE,
params: "none",
result: "{ subscribed: true }; then {\"event\": {kind, ...}} lines for every engine event until the connection closes. A subscriber that falls more than 4096 events behind is dropped and gets an {\"event\": {\"kind\": \"subscriptionLost\"}} line if possible",
},
];

View file

@ -13,6 +13,9 @@ use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use crate::Backend;
use crate::methods::{
APP_PING, ENGINE_EXECUTE, ENGINE_LIST_COMMANDS, EVENTS_SUBSCRIBE, UI_SCREENSHOT,
};
/// Largest accepted request line in bytes, newline excluded.
pub const MAX_LINE_BYTES: usize = 16 * 1024 * 1024;
@ -158,28 +161,33 @@ pub fn handle_line(line: &str, backend: &dyn Backend) -> Response {
fn dispatch(request: Request, backend: &dyn Backend) -> Response {
let Request { id, method, params } = request;
match method.as_str() {
"app.ping" => Response::ok(
APP_PING => Response::ok(
id,
json!({ "pong": true, "version": env!("CARGO_PKG_VERSION") }),
),
"engine.execute" => match serde_json::from_value::<ExecuteParams>(params) {
ENGINE_EXECUTE => match serde_json::from_value::<ExecuteParams>(params) {
Ok(p) => match backend.execute(&p.command, p.params) {
Ok(value) => Response::ok(id, value),
Err(e) => engine_error(id, &e),
},
Err(e) => Response::err(id, codes::INVALID_PARAMS, e.to_string()),
},
"engine.listCommands" => match serde_json::to_value(backend.list_commands()) {
ENGINE_LIST_COMMANDS => match serde_json::to_value(backend.list_commands()) {
Ok(list) => Response::ok(id, list),
Err(e) => Response::err(id, "internal", e.to_string()),
},
"ui.screenshot" => match serde_json::from_value::<ScreenshotParams>(params) {
UI_SCREENSHOT => match serde_json::from_value::<ScreenshotParams>(params) {
Ok(p) => match backend.screenshot(&p.path) {
Ok(()) => Response::ok(id, json!({ "path": p.path })),
Err(message) => Response::err(id, codes::SCREENSHOT_FAILED, message),
},
Err(e) => Response::err(id, codes::INVALID_PARAMS, e.to_string()),
},
EVENTS_SUBSCRIBE => Response::err(
id,
codes::INVALID_REQUEST,
"events.subscribe needs a connection to stream on",
),
other => Response::err(
id,
codes::METHOD_NOT_FOUND,
@ -234,12 +242,20 @@ mod tests {
}
Err("no window".into())
}
fn subscribe(&self, _sink: crate::EventSink) {}
}
fn call(line: &str) -> Response {
handle_line(line, &TestBackend::new())
}
#[test]
fn subscribe_needs_a_connection() {
let r = call(r#"{"id":1,"method":"events.subscribe"}"#);
assert_eq!(r.error.unwrap().code, "invalid_request");
}
#[test]
fn ping() {
let r = call(r#"{"id":1,"method":"app.ping"}"#);

View file

@ -1,15 +1,30 @@
//! The TCP side: a listener on the loopback interface, one thread per
//! connection, JSON lines in and out.
//!
//! A connection that sent `events.subscribe` also gets a forwarder thread
//! that writes event lines. Responses and events share one writer behind a
//! lock and each line is written whole, so lines never interleave. The
//! forwarder stops when the connection closes or the host drops the
//! subscription.
use std::io::{self, BufRead, BufReader, Read, Write};
use std::net::{Ipv4Addr, SocketAddr, TcpListener, TcpStream};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::mpsc::{Receiver, RecvTimeoutError, sync_channel};
use std::sync::{Arc, Mutex, PoisonError};
use std::thread;
use std::time::Duration;
use serde_json::Value;
use lutra_engine::Event;
use serde_json::{Value, json};
use crate::Backend;
use crate::protocol::{MAX_LINE_BYTES, Response, codes, handle_line};
use crate::backend::EVENT_QUEUE;
use crate::methods::EVENTS_SUBSCRIBE;
use crate::protocol::{MAX_LINE_BYTES, Response, codes, handle_line, parse_request};
/// How often an idle forwarder checks whether its connection closed.
const FORWARDER_TICK: Duration = Duration::from_millis(250);
/// A running control server.
#[derive(Debug)]
@ -54,6 +69,22 @@ fn accept_loop(listener: &TcpListener, backend: &Arc<dyn Backend>) {
}
}
/// The write side of a connection, shared by the reader and the forwarder.
type SharedWriter = Arc<Mutex<TcpStream>>;
/// Writes one line, holding the lock for the whole line.
///
/// # Errors
/// The write error.
fn write_line(writer: &SharedWriter, line: &str) -> io::Result<()> {
let mut stream = writer.lock().unwrap_or_else(PoisonError::into_inner);
let mut bytes = Vec::with_capacity(line.len() + 1);
bytes.extend_from_slice(line.as_bytes());
bytes.push(b'\n');
stream.write_all(&bytes)?;
stream.flush()
}
/// Serves one connection until the peer closes it or sends an oversized
/// line. I/O errors end the connection; the caller ignores them because the
/// peer is gone either way.
@ -61,9 +92,26 @@ fn accept_loop(listener: &TcpListener, backend: &Arc<dyn Backend>) {
/// # Errors
/// The first read or write error.
fn serve_connection(stream: TcpStream, backend: &dyn Backend) -> io::Result<()> {
let mut writer = stream.try_clone()?;
let writer: SharedWriter = Arc::new(Mutex::new(stream.try_clone()?));
let closed = Arc::new(AtomicBool::new(false));
let result = read_loop(stream, backend, &writer, &closed);
closed.store(true, Ordering::Relaxed);
result
}
/// Reads and answers request lines.
///
/// # Errors
/// The first read or write error.
fn read_loop(
stream: TcpStream,
backend: &dyn Backend,
writer: &SharedWriter,
closed: &Arc<AtomicBool>,
) -> io::Result<()> {
let mut reader = BufReader::new(stream);
let mut buf = Vec::new();
let mut subscribed = false;
loop {
buf.clear();
let limit = u64::try_from(MAX_LINE_BYTES)
@ -83,17 +131,69 @@ fn serve_connection(stream: TcpStream, backend: &dyn Backend) -> io::Result<()>
codes::LINE_TOO_LONG,
format!("request lines are limited to {MAX_LINE_BYTES} bytes"),
);
writeln!(writer, "{}", response.to_line())?;
write_line(writer, &response.to_line())?;
return Ok(());
}
if buf.iter().all(u8::is_ascii_whitespace) {
continue;
}
let response = match std::str::from_utf8(&buf) {
Ok(line) => handle_line(line, backend),
Ok(line) => match parse_request(line) {
Ok(request) if request.method == EVENTS_SUBSCRIBE => {
if !subscribed {
subscribe(backend, writer, closed)?;
subscribed = true;
}
Response::ok(request.id, json!({ "subscribed": true }))
}
_ => handle_line(line, backend),
},
Err(e) => Response::err(Value::Null, codes::PARSE_ERROR, e.to_string()),
};
writeln!(writer, "{}", response.to_line())?;
writer.flush()?;
write_line(writer, &response.to_line())?;
}
}
/// Registers a subscription with the backend and starts its forwarder.
///
/// # Errors
/// If the forwarder thread cannot be spawned.
fn subscribe(
backend: &dyn Backend,
writer: &SharedWriter,
closed: &Arc<AtomicBool>,
) -> io::Result<()> {
let (sink, events) = sync_channel(EVENT_QUEUE);
let writer = Arc::clone(writer);
let closed = Arc::clone(closed);
thread::Builder::new()
.name("lutra-control-events".into())
.spawn(move || forward(&events, &writer, &closed))?;
backend.subscribe(sink);
Ok(())
}
/// Writes events to the connection until it closes or the host drops the
/// subscription; in the latter case a final `subscriptionLost` line tells
/// the client. Write errors end forwarding because the peer is gone.
fn forward(events: &Receiver<Event>, writer: &SharedWriter, closed: &AtomicBool) {
loop {
if closed.load(Ordering::Relaxed) {
return;
}
match events.recv_timeout(FORWARDER_TICK) {
Ok(event) => {
let line = json!({ "event": event }).to_string();
if write_line(writer, &line).is_err() {
return;
}
}
Err(RecvTimeoutError::Timeout) => {}
Err(RecvTimeoutError::Disconnected) => {
let line = json!({ "event": { "kind": "subscriptionLost" } }).to_string();
let _ = write_line(writer, &line);
return;
}
}
}
}