M3.7: lutra CLI and single instance
- crates/control: rendezvous file (<data_dir>/instance.json, port + random token, atomic write, 0600 on Unix, stale detection), token-protected listener (start_with_token, app.auth first, constant-time compare, 10 s auth timeout), app.focus, and a blocking client (connect_live, request/execute/subscribe/next_event, open_folder/open_file/reveal) - lutra-desktop: a normal start forwards its path to a running instance and exits, otherwise claims the rendezvous; --control instances skip it unless LUTRA_RENDEZVOUS_DIR is set; non-Unicode args are usage errors - lutra-cli (binary lutra, now L6): path[:line[:column]] targets, folder -> project.open, file -> file.open (parent opened without a project, outside the project refused), editor.reveal, starts the desktop if needed, --wait until bufferClosed, --version/--help, exit codes 0/1/2 - tests: proptest target parsing, rendezvous read/write/stale, token check over TCP, forwarding against a test backend, --wait end to end - docs: architecture, G7, ROADMAP (agent automation 18% est.), roadmap, README Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
9ccfc1bf6a
commit
9b278099cf
26 changed files with 2162 additions and 37 deletions
425
crates/control/src/client.rs
Normal file
425
crates/control/src/client.rs
Normal file
|
|
@ -0,0 +1,425 @@
|
|||
//! A blocking client for the control channel, and the open logic the
|
||||
//! `lutra` CLI and a second app start share.
|
||||
//!
|
||||
//! [`connect_live`] reads the rendezvous file, connects to the listener it
|
||||
//! names and authenticates; [`Client::request`] sends one request and reads
|
||||
//! lines until its response arrives, keeping event lines that arrive in
|
||||
//! between for [`Client::next_event`]. Every line read is untrusted: lines
|
||||
//! are capped at [`MAX_RESPONSE_BYTES`] and malformed lines are errors,
|
||||
//! never panics.
|
||||
//!
|
||||
//! [`Client::open_folder`] and [`Client::open_file`] implement `lutra PATH`:
|
||||
//! a folder becomes the project; a file is opened with `file.open`, and if
|
||||
//! no project is open its parent folder is opened first. A file outside an
|
||||
//! open project is refused instead of replacing the project.
|
||||
|
||||
use std::collections::VecDeque;
|
||||
use std::io::{self, BufRead, BufReader, Read, Write};
|
||||
use std::net::{Ipv4Addr, SocketAddr, TcpStream};
|
||||
use std::path::Path;
|
||||
use std::thread;
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
use serde_json::{Value, json};
|
||||
|
||||
use crate::methods::{APP_AUTH, APP_FOCUS, APP_PING, ENGINE_EXECUTE, EVENTS_SUBSCRIBE};
|
||||
use crate::rendezvous::{self, Instance, ReadError};
|
||||
|
||||
/// Largest line the client reads, newline excluded. Responses carry whole
|
||||
/// buffer texts (`file.open`), so this is larger than the request cap.
|
||||
pub const MAX_RESPONSE_BYTES: usize = 64 * 1024 * 1024;
|
||||
|
||||
/// Default time to connect and to wait for one response.
|
||||
pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
|
||||
|
||||
/// Most event lines kept while waiting for a response; older ones are
|
||||
/// dropped.
|
||||
const MAX_QUEUED_EVENTS: usize = 4096;
|
||||
|
||||
/// Engine error code of a command the engine does not know, which is what
|
||||
/// a UI command answers before the window has registered it.
|
||||
const UNKNOWN_COMMAND: &str = "unknown_command";
|
||||
|
||||
/// Engine error code of a command that needs a project.
|
||||
const DISABLED: &str = "disabled";
|
||||
|
||||
/// What went wrong talking to Lutra.
|
||||
#[derive(Debug)]
|
||||
pub enum ClientError {
|
||||
/// Connecting, reading or writing failed, or the peer closed the
|
||||
/// connection.
|
||||
Io(io::Error),
|
||||
/// The peer answered with an error.
|
||||
Remote {
|
||||
/// The stable error code, e.g. `unauthorized` or `disabled`.
|
||||
code: String,
|
||||
/// The message.
|
||||
message: String,
|
||||
},
|
||||
/// The peer sent something that is not a protocol line.
|
||||
Protocol(String),
|
||||
}
|
||||
|
||||
impl ClientError {
|
||||
/// The remote error code, if this is a remote error.
|
||||
pub fn code(&self) -> Option<&str> {
|
||||
match self {
|
||||
Self::Remote { code, .. } => Some(code),
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl std::fmt::Display for ClientError {
|
||||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
match self {
|
||||
Self::Io(e) => write!(f, "{e}"),
|
||||
Self::Remote { code, message } => write!(f, "{message} ({code})"),
|
||||
Self::Protocol(why) => write!(f, "unexpected answer from Lutra: {why}"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl std::error::Error for ClientError {}
|
||||
|
||||
impl From<io::Error> for ClientError {
|
||||
fn from(e: io::Error) -> Self {
|
||||
Self::Io(e)
|
||||
}
|
||||
}
|
||||
|
||||
/// Why no running instance could be reached through the rendezvous file.
|
||||
#[derive(Debug)]
|
||||
pub enum Unavailable {
|
||||
/// There is no rendezvous file.
|
||||
Missing,
|
||||
/// The file is unreadable or invalid, or its listener does not answer
|
||||
/// or does not accept its token: the instance is gone.
|
||||
Stale(String),
|
||||
}
|
||||
|
||||
impl std::fmt::Display for Unavailable {
|
||||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
match self {
|
||||
Self::Missing => write!(f, "Lutra is not running"),
|
||||
Self::Stale(why) => write!(f, "stale rendezvous file: {why}"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Connects to the instance named by the rendezvous file in `dir`,
|
||||
/// authenticates and pings it.
|
||||
///
|
||||
/// # Errors
|
||||
/// [`Unavailable::Missing`] without a file, [`Unavailable::Stale`] if the
|
||||
/// file is invalid or nobody answers it properly within `timeout`.
|
||||
pub fn connect_live(dir: &Path, timeout: Duration) -> Result<(Instance, Client), Unavailable> {
|
||||
let instance = match rendezvous::read(dir) {
|
||||
Ok(instance) => instance,
|
||||
Err(ReadError::Missing) => return Err(Unavailable::Missing),
|
||||
Err(e) => return Err(Unavailable::Stale(e.to_string())),
|
||||
};
|
||||
match Client::connect_instance(&instance, timeout) {
|
||||
Ok(client) => Ok((instance, client)),
|
||||
Err(e) => Err(Unavailable::Stale(e.to_string())),
|
||||
}
|
||||
}
|
||||
|
||||
/// A file opened in Lutra.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct OpenedFile {
|
||||
/// The buffer id, for `bufferClosed`.
|
||||
pub id: u64,
|
||||
/// The project-relative path the engine reported.
|
||||
pub path: String,
|
||||
}
|
||||
|
||||
/// A connection to the control channel.
|
||||
#[derive(Debug)]
|
||||
pub struct Client {
|
||||
/// Read side.
|
||||
reader: BufReader<TcpStream>,
|
||||
/// Write side.
|
||||
writer: TcpStream,
|
||||
/// Bytes of a line whose end has not arrived yet (after a timeout).
|
||||
partial: Vec<u8>,
|
||||
/// Event lines read while waiting for a response.
|
||||
events: VecDeque<Value>,
|
||||
/// The id of the next request.
|
||||
next_id: u64,
|
||||
/// How long one response may take.
|
||||
timeout: Duration,
|
||||
}
|
||||
|
||||
impl Client {
|
||||
/// Connects to `127.0.0.1:port` without authenticating, for the
|
||||
/// `--control` channel.
|
||||
///
|
||||
/// # Errors
|
||||
/// The connect error.
|
||||
pub fn connect(port: u16, timeout: Duration) -> Result<Self, ClientError> {
|
||||
let addr = SocketAddr::from((Ipv4Addr::LOCALHOST, port));
|
||||
let stream = TcpStream::connect_timeout(&addr, timeout)?;
|
||||
stream.set_nodelay(true)?;
|
||||
Ok(Self {
|
||||
writer: stream.try_clone()?,
|
||||
reader: BufReader::new(stream),
|
||||
partial: Vec::new(),
|
||||
events: VecDeque::new(),
|
||||
next_id: 1,
|
||||
timeout,
|
||||
})
|
||||
}
|
||||
|
||||
/// Connects to `instance`, authenticates with its token and pings it.
|
||||
///
|
||||
/// # Errors
|
||||
/// The connect error, `unauthorized`, or a ping failure.
|
||||
pub fn connect_instance(instance: &Instance, timeout: Duration) -> Result<Self, ClientError> {
|
||||
let mut client = Self::connect(instance.port, timeout)?;
|
||||
client.request(APP_AUTH, json!({ "token": instance.token }))?;
|
||||
client.request(APP_PING, Value::Null)?;
|
||||
Ok(client)
|
||||
}
|
||||
|
||||
/// Sends one request and waits for its response; event lines read
|
||||
/// meanwhile are kept for [`Client::next_event`].
|
||||
///
|
||||
/// # Errors
|
||||
/// I/O errors and timeouts, the remote error, or a malformed line.
|
||||
pub fn request(&mut self, method: &str, params: Value) -> Result<Value, ClientError> {
|
||||
let id = self.next_id;
|
||||
self.next_id = self.next_id.saturating_add(1);
|
||||
let line = json!({ "id": id, "method": method, "params": params }).to_string();
|
||||
let mut bytes = line.into_bytes();
|
||||
bytes.push(b'\n');
|
||||
self.writer.write_all(&bytes)?;
|
||||
self.writer.flush()?;
|
||||
let deadline = Instant::now() + self.timeout;
|
||||
loop {
|
||||
let left = deadline.saturating_duration_since(Instant::now());
|
||||
if left.is_zero() {
|
||||
return Err(ClientError::Io(io::Error::new(
|
||||
io::ErrorKind::TimedOut,
|
||||
format!("no answer to {method} within {:?}", self.timeout),
|
||||
)));
|
||||
}
|
||||
let Some(value) = self.read_value(Some(left))? else {
|
||||
continue;
|
||||
};
|
||||
if let Some(event) = value.get("event") {
|
||||
if self.events.len() >= MAX_QUEUED_EVENTS {
|
||||
self.events.pop_front();
|
||||
}
|
||||
self.events.push_back(event.clone());
|
||||
continue;
|
||||
}
|
||||
if value.get("id").and_then(Value::as_u64) != Some(id) {
|
||||
continue;
|
||||
}
|
||||
if let Some(error) = value.get("error") {
|
||||
let text = |key: &str| {
|
||||
error
|
||||
.get(key)
|
||||
.and_then(Value::as_str)
|
||||
.unwrap_or_default()
|
||||
.to_string()
|
||||
};
|
||||
return Err(ClientError::Remote {
|
||||
code: text("code"),
|
||||
message: text("message"),
|
||||
});
|
||||
}
|
||||
return Ok(value.get("result").cloned().unwrap_or(Value::Null));
|
||||
}
|
||||
}
|
||||
|
||||
/// Runs an engine command (`engine.execute`).
|
||||
///
|
||||
/// # Errors
|
||||
/// As [`Client::request`].
|
||||
pub fn execute(&mut self, command: &str, params: Value) -> Result<Value, ClientError> {
|
||||
self.request(
|
||||
ENGINE_EXECUTE,
|
||||
json!({ "command": command, "params": params }),
|
||||
)
|
||||
}
|
||||
|
||||
/// Subscribes this connection to engine events.
|
||||
///
|
||||
/// # Errors
|
||||
/// As [`Client::request`].
|
||||
pub fn subscribe(&mut self) -> Result<(), ClientError> {
|
||||
self.request(EVENTS_SUBSCRIBE, Value::Null).map(|_| ())
|
||||
}
|
||||
|
||||
/// The next event (the object inside `{"event": ...}`), waiting at most
|
||||
/// `timeout` (`None`: as long as it takes).
|
||||
///
|
||||
/// # Returns
|
||||
/// `Ok(None)` on timeout.
|
||||
///
|
||||
/// # Errors
|
||||
/// [`ClientError::Io`] with `UnexpectedEof` when the connection closed,
|
||||
/// other I/O errors, or a malformed line.
|
||||
pub fn next_event(&mut self, timeout: Option<Duration>) -> Result<Option<Value>, ClientError> {
|
||||
let deadline = timeout.map(|t| Instant::now() + t);
|
||||
loop {
|
||||
if let Some(event) = self.events.pop_front() {
|
||||
return Ok(Some(event));
|
||||
}
|
||||
let left = match deadline {
|
||||
Some(deadline) => {
|
||||
let left = deadline.saturating_duration_since(Instant::now());
|
||||
if left.is_zero() {
|
||||
return Ok(None);
|
||||
}
|
||||
Some(left)
|
||||
}
|
||||
None => None,
|
||||
};
|
||||
if let Some(value) = self.read_value(left)?
|
||||
&& let Some(event) = value.get("event")
|
||||
{
|
||||
return Ok(Some(event.clone()));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Reads one line as JSON, waiting at most `timeout`.
|
||||
///
|
||||
/// # Returns
|
||||
/// `Ok(None)` if the time ran out before a whole line arrived; the part
|
||||
/// read so far is kept for the next call.
|
||||
///
|
||||
/// # Errors
|
||||
/// End of stream, other I/O errors, an oversized or malformed line.
|
||||
fn read_value(&mut self, timeout: Option<Duration>) -> Result<Option<Value>, ClientError> {
|
||||
self.reader.get_ref().set_read_timeout(timeout)?;
|
||||
let room = MAX_RESPONSE_BYTES.saturating_sub(self.partial.len());
|
||||
let limit = u64::try_from(room).unwrap_or(u64::MAX).saturating_add(1);
|
||||
let read = (&mut self.reader)
|
||||
.take(limit)
|
||||
.read_until(b'\n', &mut self.partial);
|
||||
match read {
|
||||
Ok(0) if self.partial.is_empty() => {
|
||||
return Err(ClientError::Io(io::Error::new(
|
||||
io::ErrorKind::UnexpectedEof,
|
||||
"Lutra closed the connection",
|
||||
)));
|
||||
}
|
||||
Ok(_) => {}
|
||||
Err(e)
|
||||
if matches!(
|
||||
e.kind(),
|
||||
io::ErrorKind::WouldBlock | io::ErrorKind::TimedOut
|
||||
) =>
|
||||
{
|
||||
return Ok(None);
|
||||
}
|
||||
Err(e) if e.kind() == io::ErrorKind::Interrupted => return Ok(None),
|
||||
Err(e) => return Err(ClientError::Io(e)),
|
||||
}
|
||||
if self.partial.last() != Some(&b'\n') {
|
||||
if self.partial.len() > MAX_RESPONSE_BYTES {
|
||||
return Err(ClientError::Protocol(format!(
|
||||
"a line is longer than {MAX_RESPONSE_BYTES} bytes"
|
||||
)));
|
||||
}
|
||||
return Err(ClientError::Io(io::Error::new(
|
||||
io::ErrorKind::UnexpectedEof,
|
||||
"Lutra closed the connection in the middle of a line",
|
||||
)));
|
||||
}
|
||||
let line = std::mem::take(&mut self.partial);
|
||||
serde_json::from_slice(&line)
|
||||
.map(Some)
|
||||
.map_err(|e| ClientError::Protocol(e.to_string()))
|
||||
}
|
||||
|
||||
/// Brings the window to the front. Failures are ignored by callers that
|
||||
/// only want to be helpful (there may be no window yet).
|
||||
///
|
||||
/// # Errors
|
||||
/// As [`Client::request`].
|
||||
pub fn focus(&mut self) -> Result<(), ClientError> {
|
||||
self.request(APP_FOCUS, Value::Null).map(|_| ())
|
||||
}
|
||||
|
||||
/// Opens `folder` as the project (`project.open`).
|
||||
///
|
||||
/// # Errors
|
||||
/// The engine's error, e.g. `unsaved_changes` when the open project has
|
||||
/// dirty buffers.
|
||||
pub fn open_folder(&mut self, folder: &Path) -> Result<Value, ClientError> {
|
||||
self.execute("project.open", json!({ "path": path_text(folder)? }))
|
||||
}
|
||||
|
||||
/// Opens `file` in a tab. If no project is open, the file's parent
|
||||
/// folder is opened as the project first. A file outside the open
|
||||
/// project fails with the engine's error; the project is never replaced
|
||||
/// behind the user's back.
|
||||
///
|
||||
/// # Errors
|
||||
/// The engine's error, or [`ClientError::Protocol`] for a result
|
||||
/// without a buffer id.
|
||||
pub fn open_file(&mut self, file: &Path) -> Result<OpenedFile, ClientError> {
|
||||
let text = path_text(file)?;
|
||||
let result = match self.execute("file.open", json!({ "path": text })) {
|
||||
Err(e) if e.code() == Some(DISABLED) => {
|
||||
let parent = file.parent().ok_or_else(|| {
|
||||
ClientError::Protocol(format!("{} has no parent folder", file.display()))
|
||||
})?;
|
||||
self.open_folder(parent)?;
|
||||
self.execute("file.open", json!({ "path": text }))?
|
||||
}
|
||||
other => other?,
|
||||
};
|
||||
let id = result
|
||||
.get("id")
|
||||
.and_then(Value::as_u64)
|
||||
.ok_or_else(|| ClientError::Protocol("file.open returned no buffer id".into()))?;
|
||||
let path = result
|
||||
.get("path")
|
||||
.and_then(Value::as_str)
|
||||
.map_or_else(|| text.clone(), str::to_string);
|
||||
Ok(OpenedFile { id, path })
|
||||
}
|
||||
|
||||
/// Moves the cursor of the open tab `path` to 0-based `line` and
|
||||
/// UTF-16 `column` with the UI command `editor.reveal`. Until the
|
||||
/// window has registered its UI commands (it is still starting) the
|
||||
/// engine answers `unknown_command`; the call is retried until `wait`
|
||||
/// has passed.
|
||||
///
|
||||
/// # Errors
|
||||
/// The last error once `wait` has passed, or any other error at once.
|
||||
pub fn reveal(
|
||||
&mut self,
|
||||
path: &str,
|
||||
line: u32,
|
||||
column: u32,
|
||||
wait: Duration,
|
||||
) -> Result<(), ClientError> {
|
||||
let deadline = Instant::now() + wait;
|
||||
let params = json!({ "path": path, "line": line, "column": column });
|
||||
loop {
|
||||
match self.execute("editor.reveal", params.clone()) {
|
||||
Err(e) if e.code() == Some(UNKNOWN_COMMAND) && Instant::now() < deadline => {
|
||||
thread::sleep(Duration::from_millis(200));
|
||||
}
|
||||
other => return other.map(|_| ()),
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// The path as UTF-8 text for a JSON param.
|
||||
///
|
||||
/// # Errors
|
||||
/// [`ClientError::Protocol`] if the path is not valid Unicode.
|
||||
fn path_text(path: &Path) -> Result<String, ClientError> {
|
||||
path.to_str()
|
||||
.map(str::to_string)
|
||||
.ok_or_else(|| ClientError::Protocol(format!("{} is not valid Unicode", path.display())))
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue