Step 1 of M3.5: the shared mechanism. M3.4 and M3.5 build on it. - Engine: `Outcome.pending: Option<Pending>`. `Pending::new(rx, timeout, finish)`; `Pending::wait()` is called without the engine lock and returns at the answer, a dropped sender or the deadline (timeout + 1 s). `Engine::resolve(answered)` then runs `finish(state, reply)` inside the guard, under the lock. `run_waiting(lock, cmd, params, publish)` does all three steps for hosts. - Hosts: `Host::run`, `testkit::EngineBackend` and the control test backend use `run_waiting`. - New IPC `engine_execute_waiting` (`#[tauri::command(async)]`, off the main thread) with `runWaiting()` in `ui/src/ipc.ts`. Only `lsp.*` requests use it. Ordering guarantee: - `engine_execute` stays synchronous on the main thread, so ordinary commands (`buffer.edit`) still run in call order. - The order towards the server is fixed under the engine lock: `buffer.edit` queues its didChange on the session's FIFO queue before it returns, and `lsp::submit` queues the request on the same queue. A request therefore sees every edit whose `buffer.edit` returned first, and the UI awaits the sync's `idle()` before sending one. Failures: - A stall is caught by the request timeout, with the deadline as backstop. - On restart, close, quit or crash the request is dropped or resolved as stopped, so the waiter gets an error, never a hang. Tests: `crates/engine/tests/pending.rs` (answer, lock free while waiting, dropped sender, deadline, resolve, lsp.restart while a request is pending) and Vitest for `runWaiting`. Gate: 13 steps, 321 s, Vitest 443 + 1 skipped. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
228 lines
7.5 KiB
Rust
228 lines
7.5 KiB
Rust
//! The command abstraction: static metadata, the run contract and the
|
|
//! effects a command asks its host to carry out.
|
|
|
|
use serde::Serialize;
|
|
use serde_json::Value;
|
|
|
|
use crate::{EngineError, Event, State};
|
|
|
|
/// Static metadata of a command.
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
pub struct CommandSpec {
|
|
/// Unique id, `area.action` in camelCase, e.g. `app.about`.
|
|
pub id: &'static str,
|
|
/// Label for menus and the command palette, in English.
|
|
pub label: &'static str,
|
|
/// Menu path with `/` separators, e.g. `Help/About Lutra`.
|
|
pub menu_path: Option<&'static str>,
|
|
/// Default shortcut in Lutra notation; `Mod` is Ctrl, or Cmd on macOS.
|
|
pub default_shortcut: Option<&'static str>,
|
|
/// Documentation of the params object, `none` if the command takes none.
|
|
pub params: &'static str,
|
|
}
|
|
|
|
/// Something the engine asks its host to do after a command returns,
|
|
/// because it needs a layer the engine cannot reach (windows, the process).
|
|
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
|
|
#[serde(tag = "kind", rename_all = "camelCase")]
|
|
pub enum Effect {
|
|
/// Quit the application.
|
|
Quit,
|
|
/// Show the native folder picker and run `project.open` with the chosen
|
|
/// folder. Cancelling the picker does nothing and is not an error.
|
|
PickFolder,
|
|
}
|
|
|
|
/// Result of a successful command.
|
|
#[derive(Debug, Default)]
|
|
pub struct Outcome {
|
|
/// JSON result returned to the caller.
|
|
pub value: Value,
|
|
/// Effects for the host to apply, in order.
|
|
pub effects: Vec<Effect>,
|
|
/// State changes for the host to publish, oldest first. Filled by the
|
|
/// engine from the events the command queued; commands leave it empty.
|
|
pub events: Vec<Event>,
|
|
/// An answer the command is still waiting for (a language server
|
|
/// request). The host waits for it with [`Pending::wait`] without the
|
|
/// engine lock and finishes it with [`crate::Engine::resolve`]; the
|
|
/// caller's result is the resolved value, not [`Outcome::value`].
|
|
pub pending: Option<Pending>,
|
|
}
|
|
|
|
impl Outcome {
|
|
/// An outcome with a value and no effects.
|
|
pub fn value(value: Value) -> Self {
|
|
Self {
|
|
value,
|
|
..Self::default()
|
|
}
|
|
}
|
|
|
|
/// An outcome with a null value and one effect.
|
|
pub fn effect(effect: Effect) -> Self {
|
|
Self {
|
|
effects: vec![effect],
|
|
..Self::default()
|
|
}
|
|
}
|
|
|
|
/// An outcome whose value comes later from `pending`.
|
|
pub fn pending(pending: Pending) -> Self {
|
|
Self {
|
|
pending: Some(pending),
|
|
..Self::default()
|
|
}
|
|
}
|
|
}
|
|
|
|
/// The answer a language server request delivers: its result, its error,
|
|
/// or `None` when it never came (timeout, the session ended).
|
|
pub type Reply = Option<Result<Value, lutra_lsp::LspError>>;
|
|
|
|
/// Turns a [`Reply`] into the command's value, under the engine lock.
|
|
type Finish = Box<dyn FnOnce(&mut State, Reply) -> Result<Value, EngineError> + Send>;
|
|
|
|
/// A command result that waits for an answer from outside the engine.
|
|
///
|
|
/// Waiting never holds the engine lock: hosts call [`Pending::wait`] after
|
|
/// releasing it, then [`crate::Engine::resolve`] with the lock to turn the
|
|
/// answer into the value (which may change the state, as a rename does).
|
|
pub struct Pending {
|
|
/// Where the answer arrives.
|
|
receiver: std::sync::mpsc::Receiver<Result<Value, lutra_lsp::LspError>>,
|
|
/// How long to wait at most.
|
|
timeout: std::time::Duration,
|
|
/// What to do with it.
|
|
finish: Finish,
|
|
}
|
|
|
|
impl std::fmt::Debug for Pending {
|
|
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
|
f.debug_struct("Pending")
|
|
.field("timeout", &self.timeout)
|
|
.finish_non_exhaustive()
|
|
}
|
|
}
|
|
|
|
impl Pending {
|
|
/// A pending result.
|
|
///
|
|
/// # Parameters
|
|
/// - `receiver`: receives the answer; a dropped sender counts as no
|
|
/// answer.
|
|
/// - `timeout`: the longest wait; the request's own timeout should be
|
|
/// shorter, so it reports first.
|
|
/// - `finish`: builds the value from the answer, under the lock.
|
|
pub fn new(
|
|
receiver: std::sync::mpsc::Receiver<Result<Value, lutra_lsp::LspError>>,
|
|
timeout: std::time::Duration,
|
|
finish: impl FnOnce(&mut State, Reply) -> Result<Value, EngineError> + Send + 'static,
|
|
) -> Self {
|
|
Self {
|
|
receiver,
|
|
timeout,
|
|
finish: Box::new(finish),
|
|
}
|
|
}
|
|
|
|
/// Blocks until the answer arrives, the sender is dropped or the
|
|
/// timeout (plus one second of grace) passes. Call it without the
|
|
/// engine lock.
|
|
pub fn wait(self) -> Answered {
|
|
let reply = self
|
|
.receiver
|
|
.recv_timeout(self.timeout + std::time::Duration::from_secs(1))
|
|
.ok();
|
|
Answered {
|
|
reply,
|
|
finish: self.finish,
|
|
}
|
|
}
|
|
}
|
|
|
|
/// A [`Pending`] whose answer arrived (or never will); pass it to
|
|
/// [`crate::Engine::resolve`].
|
|
pub struct Answered {
|
|
/// The answer.
|
|
reply: Reply,
|
|
/// What to do with it.
|
|
finish: Finish,
|
|
}
|
|
|
|
impl std::fmt::Debug for Answered {
|
|
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
|
f.debug_struct("Answered")
|
|
.field("reply", &self.reply)
|
|
.finish_non_exhaustive()
|
|
}
|
|
}
|
|
|
|
impl Answered {
|
|
/// Builds the value; for [`crate::Engine::resolve`].
|
|
pub(crate) fn finish(self, state: &mut State) -> Result<Value, EngineError> {
|
|
(self.finish)(state, self.reply)
|
|
}
|
|
}
|
|
|
|
/// A user-visible action.
|
|
///
|
|
/// Implementations are stateless; everything they change lives in [`State`].
|
|
pub trait Command: Send + Sync {
|
|
/// Static metadata.
|
|
fn spec(&self) -> &CommandSpec;
|
|
|
|
/// Whether the command can run in the given state. Defaults to always.
|
|
fn enabled(&self, _state: &State) -> bool {
|
|
true
|
|
}
|
|
|
|
/// Runs the command.
|
|
///
|
|
/// # Errors
|
|
/// Returns [`EngineError::InvalidParams`] for params that don't match
|
|
/// [`CommandSpec::params`], and [`EngineError::Failed`] when the action
|
|
/// itself fails.
|
|
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError>;
|
|
}
|
|
|
|
/// Description of a command for menus, the palette, keymaps and agents.
|
|
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct CommandInfo {
|
|
/// Command id.
|
|
pub id: String,
|
|
/// Label.
|
|
pub label: String,
|
|
/// Menu path, if the command is in a menu.
|
|
pub menu_path: Option<String>,
|
|
/// Default shortcut, if any.
|
|
pub default_shortcut: Option<String>,
|
|
/// Params documentation.
|
|
pub params: String,
|
|
/// Whether the command can run in the current state.
|
|
pub enabled: bool,
|
|
/// Message-catalog key of the label; set for UI commands, whose `label`
|
|
/// is the same key because the engine has no English text for them.
|
|
#[serde(skip_serializing_if = "Option::is_none")]
|
|
pub label_key: Option<String>,
|
|
/// Whether the frontend registered the command (`ui.registerCommands`)
|
|
/// and runs it; running it through the engine emits `uiCommand`.
|
|
pub ui: bool,
|
|
}
|
|
|
|
impl CommandInfo {
|
|
/// Builds the description from a spec and the current enabled state.
|
|
pub fn new(spec: &CommandSpec, enabled: bool) -> Self {
|
|
Self {
|
|
id: spec.id.to_string(),
|
|
label: spec.label.to_string(),
|
|
menu_path: spec.menu_path.map(str::to_string),
|
|
default_shortcut: spec.default_shortcut.map(str::to_string),
|
|
params: spec.params.to_string(),
|
|
enabled,
|
|
label_key: None,
|
|
ui: false,
|
|
}
|
|
}
|
|
}
|