Lutra/crates/engine/src/command.rs
danny 20d1d28c32 M3.5: pending outcomes for commands that wait for the language server
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>
2026-10-22 06:36:20 +02:00

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,
}
}
}