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:
danny 2026-10-18 00:23:09 +02:00
parent 9ccfc1bf6a
commit 9b278099cf
26 changed files with 2162 additions and 37 deletions

View file

@ -12,6 +12,7 @@ publish.workspace = true
layer = 5
[dependencies]
getrandom = "0.3.4"
lutra-engine.workspace = true
serde = { version = "1.0.229", features = ["derive"] }
serde_json = "1.0.154"

View file

@ -39,6 +39,15 @@ pub trait Backend: Send + Sync + 'static {
/// Adds a subscriber that receives every engine event from now on.
fn subscribe(&self, sink: EventSink);
/// Brings the main window to the front, for the CLI and a second app
/// start. The default has no window and fails.
///
/// # Errors
/// A message if there is no window or it cannot be focused.
fn focus(&self) -> Result<(), String> {
Err("there is no window".into())
}
}
/// The event subscribers of a host.

View 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())))
}

View file

@ -6,11 +6,18 @@
//! single lines, [`server`] owns the sockets, [`methods`] lists the
//! methods. Hosts plug in through [`Backend`] and publish engine events to
//! subscribed connections through [`Subscribers`].
//!
//! The single instance (M3.7) adds [`rendezvous`], the per-user file that
//! names the token-protected listener of the running app, and [`client`],
//! the client that the `lutra` CLI, a second app start and `lutra mcp` use
//! to reach it.
mod backend;
pub mod client;
pub mod methods;
pub mod protocol;
pub mod rendezvous;
pub mod server;
pub use backend::{Backend, EVENT_QUEUE, EventSink, Subscribers};
pub use server::{ServerHandle, start};
pub use server::{ServerHandle, start, start_with_token};

View file

@ -15,6 +15,10 @@ pub const ENGINE_LIST_COMMANDS: &str = "engine.listCommands";
pub const UI_SCREENSHOT: &str = "ui.screenshot";
/// `events.subscribe`: streams engine events on this connection.
pub const EVENTS_SUBSCRIBE: &str = "events.subscribe";
/// `app.auth`: authenticates a connection to the rendezvous listener.
pub const APP_AUTH: &str = "app.auth";
/// `app.focus`: brings the main window to the front.
pub const APP_FOCUS: &str = "app.focus";
/// Documentation of one method.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
@ -29,6 +33,16 @@ pub struct MethodDoc {
/// Every method, for help output and agents.
pub const METHODS: &[MethodDoc] = &[
MethodDoc {
name: APP_AUTH,
params: "{ token: string }",
result: "{ authenticated: true }. On the rendezvous listener it must be the first request; any other first request or a wrong token gets error unauthorized and the connection is closed. On the --control listener it always succeeds",
},
MethodDoc {
name: APP_FOCUS,
params: "none",
result: "{ focused: true }; error focus_failed if there is no window",
},
MethodDoc {
name: APP_PING,
params: "none",

View file

@ -14,7 +14,8 @@ use serde_json::{Value, json};
use crate::Backend;
use crate::methods::{
APP_PING, ENGINE_EXECUTE, ENGINE_LIST_COMMANDS, EVENTS_SUBSCRIBE, UI_SCREENSHOT,
APP_AUTH, APP_FOCUS, APP_PING, ENGINE_EXECUTE, ENGINE_LIST_COMMANDS, EVENTS_SUBSCRIBE,
UI_SCREENSHOT,
};
/// Largest accepted request line in bytes, newline excluded.
@ -35,6 +36,10 @@ pub mod codes {
pub const LINE_TOO_LONG: &str = "line_too_long";
/// The screenshot could not be taken.
pub const SCREENSHOT_FAILED: &str = "screenshot_failed";
/// The connection has not authenticated with the right token.
pub const UNAUTHORIZED: &str = "unauthorized";
/// The window could not be brought to the front.
pub const FOCUS_FAILED: &str = "focus_failed";
}
/// A parsed request.
@ -143,6 +148,14 @@ pub fn parse_request(line: &str) -> Result<Request, Response> {
.map_err(|e| Response::err(echo, codes::INVALID_REQUEST, e.to_string()))
}
/// Params of `app.auth`.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AuthParams {
/// The token from the rendezvous file.
pub token: String,
}
/// Answers one request line. Never panics: a panic in the backend becomes an
/// `internal` error response.
pub fn handle_line(line: &str, backend: &dyn Backend) -> Response {
@ -183,6 +196,11 @@ fn dispatch(request: Request, backend: &dyn Backend) -> Response {
},
Err(e) => Response::err(id, codes::INVALID_PARAMS, e.to_string()),
},
APP_AUTH => Response::ok(id, json!({ "authenticated": true })),
APP_FOCUS => match backend.focus() {
Ok(()) => Response::ok(id, json!({ "focused": true })),
Err(message) => Response::err(id, codes::FOCUS_FAILED, message),
},
EVENTS_SUBSCRIBE => Response::err(
id,
codes::INVALID_REQUEST,
@ -256,6 +274,14 @@ mod tests {
assert_eq!(r.error.unwrap().code, "invalid_request");
}
#[test]
fn auth_and_focus_on_an_open_channel() {
let r = call(r#"{"id":1,"method":"app.auth","params":{"token":"x"}}"#);
assert_eq!(r.result.unwrap()["authenticated"], true);
let r = call(r#"{"id":2,"method":"app.focus"}"#);
assert_eq!(r.error.unwrap().code, "focus_failed");
}
#[test]
fn ping() {
let r = call(r#"{"id":1,"method":"app.ping"}"#);

View file

@ -0,0 +1,288 @@
//! The single-instance rendezvous file.
//!
//! A desktop app that owns the single instance writes `instance.json` into
//! its data directory: the port of a token-protected control listener on
//! `127.0.0.1`, a random token, its process id and its version. The `lutra`
//! CLI, a second app start and (from M3.8) `lutra mcp` read the file,
//! connect to the port and authenticate with `app.auth {token}` before any
//! other request (see [`crate::client::Client::connect_instance`]).
//!
//! The file is the only place the token is stored, so it must be readable
//! by the user only. On Unix it is created with mode `0600`. On Windows it
//! lives in the user's roaming application data folder, whose ACL grants
//! access to the user, `SYSTEM` and administrators only; the file inherits
//! that ACL. A file whose listener does not answer, or answers without
//! accepting the token, is stale: the next app start replaces it.
//!
//! The directory is [`dir`]: `LUTRA_RENDEZVOUS_DIR` if set, otherwise
//! [`default_data_dir`], which matches Tauri's `app_data_dir()` for the
//! identifier [`APP_IDENTIFIER`].
use std::fs::{self, File, OpenOptions};
use std::io::{self, Read, Write};
use std::path::{Path, PathBuf};
use serde::{Deserialize, Serialize};
/// Name of the rendezvous file inside its directory.
pub const FILE_NAME: &str = "instance.json";
/// Environment variable that overrides the rendezvous directory. Tests and
/// isolated live checks set it; a desktop started with `--control PORT`
/// takes part in the single instance only when it is set.
pub const DIR_ENV: &str = "LUTRA_RENDEZVOUS_DIR";
/// The Tauri app identifier, the last part of the data directory.
pub const APP_IDENTIFIER: &str = "dev.lutra.desktop";
/// Random bytes in a token; the token is their lowercase hex form.
pub const TOKEN_BYTES: usize = 32;
/// Largest rendezvous file that is read; anything bigger is invalid.
pub const MAX_FILE_BYTES: u64 = 4096;
/// The contents of the rendezvous file.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Instance {
/// Port of the token-protected control listener on `127.0.0.1`.
pub port: u16,
/// Token for `app.auth`, [`TOKEN_BYTES`] random bytes as hex.
pub token: String,
/// Process id of the instance, for diagnostics only.
pub pid: u32,
/// Version of the instance.
pub version: String,
}
/// Why the rendezvous file could not be read.
#[derive(Debug)]
pub enum ReadError {
/// There is no file: no instance has claimed the directory.
Missing,
/// The file exists but is too big, not JSON or not an [`Instance`].
Invalid(String),
/// The file could not be read.
Io(io::Error),
}
impl std::fmt::Display for ReadError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Missing => write!(f, "no rendezvous file"),
Self::Invalid(why) => write!(f, "invalid rendezvous file: {why}"),
Self::Io(e) => write!(f, "cannot read the rendezvous file: {e}"),
}
}
}
impl std::error::Error for ReadError {}
/// The rendezvous directory: `LUTRA_RENDEZVOUS_DIR` if set and not empty,
/// otherwise [`default_data_dir`].
pub fn dir() -> Option<PathBuf> {
match std::env::var_os(DIR_ENV) {
Some(value) if !value.is_empty() => Some(PathBuf::from(value)),
_ => default_data_dir(),
}
}
/// The app data directory as Tauri computes it for [`APP_IDENTIFIER`]:
/// `%APPDATA%\<id>` on Windows, `~/Library/Application Support/<id>` on
/// macOS, `$XDG_DATA_HOME/<id>` or `~/.local/share/<id>` elsewhere. `None`
/// if the needed environment variables are missing or relative.
pub fn default_data_dir() -> Option<PathBuf> {
let absolute = |name: &str| {
std::env::var_os(name)
.map(PathBuf::from)
.filter(|p| p.is_absolute())
};
let base = if cfg!(windows) {
absolute("APPDATA")?
} else if cfg!(target_os = "macos") {
absolute("HOME")?
.join("Library")
.join("Application Support")
} else {
absolute("XDG_DATA_HOME")
.or_else(|| Some(absolute("HOME")?.join(".local").join("share")))?
};
Some(base.join(APP_IDENTIFIER))
}
/// The path of the rendezvous file in `dir`.
pub fn path(dir: &Path) -> PathBuf {
dir.join(FILE_NAME)
}
/// A new random token from the operating system's generator.
///
/// # Errors
/// If the generator fails.
pub fn new_token() -> io::Result<String> {
let mut bytes = [0u8; TOKEN_BYTES];
getrandom::fill(&mut bytes).map_err(|e| io::Error::other(e.to_string()))?;
Ok(bytes.iter().map(|b| format!("{b:02x}")).collect())
}
/// Compares two tokens in time that depends only on their lengths, so a
/// client cannot find the token byte by byte by timing rejections.
pub fn tokens_match(given: &str, expected: &str) -> bool {
let (a, b) = (given.as_bytes(), expected.as_bytes());
if a.len() != b.len() {
return false;
}
a.iter().zip(b).fold(0u8, |acc, (x, y)| acc | (x ^ y)) == 0
}
/// Reads the rendezvous file in `dir`.
///
/// # Errors
/// [`ReadError::Missing`] without a file, [`ReadError::Invalid`] for a file
/// over [`MAX_FILE_BYTES`] or with the wrong shape, [`ReadError::Io`] for
/// other read failures.
pub fn read(dir: &Path) -> Result<Instance, ReadError> {
let file = match File::open(path(dir)) {
Ok(file) => file,
Err(e) if e.kind() == io::ErrorKind::NotFound => return Err(ReadError::Missing),
Err(e) => return Err(ReadError::Io(e)),
};
let mut bytes = Vec::new();
file.take(MAX_FILE_BYTES + 1)
.read_to_end(&mut bytes)
.map_err(ReadError::Io)?;
if bytes.len() as u64 > MAX_FILE_BYTES {
return Err(ReadError::Invalid(format!(
"larger than {MAX_FILE_BYTES} bytes"
)));
}
serde_json::from_slice(&bytes).map_err(|e| ReadError::Invalid(e.to_string()))
}
/// Writes `instance` as the rendezvous file in `dir`, replacing any file
/// there. The directory is created if needed. The text goes to a temporary
/// file in the same directory first (mode `0600` on Unix) and is renamed
/// over the old file, so readers never see half a file.
///
/// # Errors
/// If the directory, the temporary file or the rename fails.
pub fn write(dir: &Path, instance: &Instance) -> io::Result<()> {
fs::create_dir_all(dir)?;
let text = serde_json::to_vec(instance).map_err(io::Error::other)?;
let tmp = dir.join(format!("{FILE_NAME}.{}.tmp", std::process::id()));
let result = write_private(&tmp, &text).and_then(|()| fs::rename(&tmp, path(dir)));
if result.is_err() {
let _ = fs::remove_file(&tmp);
}
result
}
/// Creates `path` readable and writable by the owner only and writes
/// `bytes` to it.
///
/// # Errors
/// If the file cannot be created or written.
fn write_private(path: &Path, bytes: &[u8]) -> io::Result<()> {
let mut options = OpenOptions::new();
options.write(true).create(true).truncate(true);
#[cfg(unix)]
{
use std::os::unix::fs::OpenOptionsExt;
options.mode(0o600);
}
let mut file = options.open(path)?;
file.write_all(bytes)?;
file.sync_all()
}
/// Removes the rendezvous file in `dir` if it still holds `token`, so an
/// instance that exits never deletes the file of a newer one.
///
/// # Errors
/// If the file holds `token` but cannot be removed.
pub fn remove_if_ours(dir: &Path, token: &str) -> io::Result<()> {
match read(dir) {
Ok(instance) if tokens_match(&instance.token, token) => fs::remove_file(path(dir)),
_ => Ok(()),
}
}
#[cfg(test)]
mod tests {
use super::*;
fn instance(token: &str) -> Instance {
Instance {
port: 4242,
token: token.into(),
pid: 7,
version: "0.0.0".into(),
}
}
#[test]
fn tokens_are_random_hex() {
let a = new_token().unwrap();
let b = new_token().unwrap();
assert_eq!(a.len(), TOKEN_BYTES * 2);
assert!(a.chars().all(|c| c.is_ascii_hexdigit()));
assert_ne!(a, b);
}
#[test]
fn compares_tokens() {
assert!(tokens_match("abc", "abc"));
assert!(!tokens_match("abd", "abc"));
assert!(!tokens_match("ab", "abc"));
assert!(!tokens_match("", "abc"));
}
#[test]
fn writes_reads_and_replaces() {
let dir = tempfile::tempdir().unwrap();
let nested = dir.path().join("a").join("b");
assert!(matches!(read(&nested), Err(ReadError::Missing)));
write(&nested, &instance("one")).unwrap();
assert_eq!(read(&nested).unwrap(), instance("one"));
write(&nested, &instance("two")).unwrap();
assert_eq!(read(&nested).unwrap().token, "two");
let leftovers: Vec<_> = fs::read_dir(&nested).unwrap().collect();
assert_eq!(leftovers.len(), 1, "no temporary file is left behind");
}
#[test]
fn rejects_broken_files() {
let dir = tempfile::tempdir().unwrap();
fs::write(path(dir.path()), b"{not json").unwrap();
assert!(matches!(read(dir.path()), Err(ReadError::Invalid(_))));
fs::write(
path(dir.path()),
br#"{"port":70000,"token":"x","pid":1,"version":"v"}"#,
)
.unwrap();
assert!(matches!(read(dir.path()), Err(ReadError::Invalid(_))));
fs::write(path(dir.path()), vec![b' '; 5000]).unwrap();
assert!(matches!(read(dir.path()), Err(ReadError::Invalid(_))));
}
#[test]
fn removes_only_its_own_file() {
let dir = tempfile::tempdir().unwrap();
write(dir.path(), &instance("newer")).unwrap();
remove_if_ours(dir.path(), "older").unwrap();
assert!(path(dir.path()).exists());
remove_if_ours(dir.path(), "newer").unwrap();
assert!(!path(dir.path()).exists());
remove_if_ours(dir.path(), "newer").unwrap();
}
#[cfg(unix)]
#[test]
fn file_is_private_on_unix() {
use std::os::unix::fs::PermissionsExt;
let dir = tempfile::tempdir().unwrap();
write(dir.path(), &instance("t")).unwrap();
let mode = fs::metadata(path(dir.path())).unwrap().permissions().mode();
assert_eq!(mode & 0o777, 0o600);
}
}

View file

@ -1,6 +1,12 @@
//! The TCP side: a listener on the loopback interface, one thread per
//! connection, JSON lines in and out.
//!
//! [`start`] serves the open `--control PORT` channel. [`start_with_token`]
//! serves the rendezvous listener of the single instance: there the first
//! request must be `app.auth {token}` with the token of the rendezvous
//! file, sent within [`AUTH_TIMEOUT`]; anything else gets `unauthorized`
//! and the connection is closed.
//!
//! 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
@ -20,12 +26,28 @@ use serde_json::{Value, json};
use crate::Backend;
use crate::backend::EVENT_QUEUE;
use crate::methods::EVENTS_SUBSCRIBE;
use crate::protocol::{MAX_LINE_BYTES, Response, codes, handle_line, parse_request};
use crate::methods::{APP_AUTH, EVENTS_SUBSCRIBE};
use crate::protocol::{
AuthParams, MAX_LINE_BYTES, Request, Response, codes, handle_line, parse_request,
};
use crate::rendezvous::tokens_match;
/// How often an idle forwarder checks whether its connection closed.
const FORWARDER_TICK: Duration = Duration::from_millis(250);
/// How long a connection to the rendezvous listener may take to
/// authenticate before it is closed.
pub const AUTH_TIMEOUT: Duration = Duration::from_secs(10);
/// Who may use a listener's connections.
#[derive(Debug, Clone)]
enum Access {
/// Everyone who can reach `127.0.0.1` (the `--control` channel).
Open,
/// Connections that authenticated with this token first.
Token(Arc<str>),
}
/// A running control server.
#[derive(Debug)]
pub struct ServerHandle {
@ -46,24 +68,47 @@ impl ServerHandle {
/// # Errors
/// The bind error, e.g. when the port is taken.
pub fn start(port: u16, backend: Arc<dyn Backend>) -> io::Result<ServerHandle> {
serve(port, backend, Access::Open)
}
/// Binds `127.0.0.1:port` (0 for any free port) and serves requests from
/// connections that authenticate with `token` first, for the rest of the
/// process's life.
///
/// # Errors
/// The bind error.
pub fn start_with_token(
port: u16,
backend: Arc<dyn Backend>,
token: &str,
) -> io::Result<ServerHandle> {
serve(port, backend, Access::Token(Arc::from(token)))
}
/// Binds the listener and starts the accept thread.
///
/// # Errors
/// The bind error.
fn serve(port: u16, backend: Arc<dyn Backend>, access: Access) -> io::Result<ServerHandle> {
let listener = TcpListener::bind((Ipv4Addr::LOCALHOST, port))?;
let addr = listener.local_addr()?;
thread::Builder::new()
.name("lutra-control".into())
.spawn(move || accept_loop(&listener, &backend))?;
.spawn(move || accept_loop(&listener, &backend, &access))?;
Ok(ServerHandle { addr })
}
/// Accepts connections until the listener fails. Failed accepts and threads
/// that cannot be spawned drop that one connection and keep serving.
fn accept_loop(listener: &TcpListener, backend: &Arc<dyn Backend>) {
fn accept_loop(listener: &TcpListener, backend: &Arc<dyn Backend>, access: &Access) {
for stream in listener.incoming() {
let Ok(stream) = stream else { continue };
let backend = Arc::clone(backend);
let access = access.clone();
let spawned = thread::Builder::new()
.name("lutra-control-conn".into())
.spawn(move || {
let _ = serve_connection(stream, backend.as_ref());
let _ = serve_connection(stream, backend.as_ref(), &access);
});
drop(spawned);
}
@ -91,24 +136,31 @@ fn write_line(writer: &SharedWriter, line: &str) -> io::Result<()> {
///
/// # Errors
/// The first read or write error.
fn serve_connection(stream: TcpStream, backend: &dyn Backend) -> io::Result<()> {
fn serve_connection(stream: TcpStream, backend: &dyn Backend, access: &Access) -> io::Result<()> {
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);
let result = read_loop(stream, backend, access, &writer, &closed);
closed.store(true, Ordering::Relaxed);
result
}
/// Reads and answers request lines.
/// Reads and answers request lines. On a token listener the first request
/// must authenticate (see [`authenticate`]); until then reads time out after
/// [`AUTH_TIMEOUT`].
///
/// # Errors
/// The first read or write error.
fn read_loop(
stream: TcpStream,
backend: &dyn Backend,
access: &Access,
writer: &SharedWriter,
closed: &Arc<AtomicBool>,
) -> io::Result<()> {
let mut authenticated = matches!(access, Access::Open);
if !authenticated {
stream.set_read_timeout(Some(AUTH_TIMEOUT))?;
}
let mut reader = BufReader::new(stream);
let mut buf = Vec::new();
let mut subscribed = false;
@ -137,6 +189,20 @@ fn read_loop(
if buf.iter().all(u8::is_ascii_whitespace) {
continue;
}
if !authenticated {
let Access::Token(token) = access else {
return Ok(());
};
let response = authenticate(&buf, token);
let accepted = response.error.is_none();
write_line(writer, &response.to_line())?;
if !accepted {
return Ok(());
}
authenticated = true;
reader.get_ref().set_read_timeout(None)?;
continue;
}
let response = match std::str::from_utf8(&buf) {
Ok(line) => match parse_request(line) {
Ok(request) if request.method == EVENTS_SUBSCRIBE => {
@ -154,6 +220,32 @@ fn read_loop(
}
}
/// Answers the first request of a token connection: `app.auth` with the
/// right token succeeds, everything else is `unauthorized`. The message
/// does not say whether the token or the method was wrong.
fn authenticate(line: &[u8], token: &str) -> Response {
let request = std::str::from_utf8(line)
.ok()
.and_then(|line| parse_request(line).ok());
let id = request.as_ref().map_or(Value::Null, |r| r.id.clone());
let accepted = match request {
Some(Request { method, params, .. }) if method == APP_AUTH => {
serde_json::from_value::<AuthParams>(params)
.is_ok_and(|p| tokens_match(&p.token, token))
}
_ => false,
};
if accepted {
Response::ok(id, json!({ "authenticated": true }))
} else {
Response::err(
id,
codes::UNAUTHORIZED,
"authenticate with app.auth and the rendezvous token first",
)
}
}
/// Registers a subscription with the backend and starts its forwarder.
///
/// # Errors

View file

@ -0,0 +1,212 @@
//! The single instance over real sockets: the token check of the
//! rendezvous listener, stale rendezvous files, and forwarding a second
//! start's path to the running instance.
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::indexing_slicing)]
use std::io::{BufRead, BufReader, Write};
use std::net::TcpStream;
use std::path::Path;
use std::sync::Arc;
use std::time::Duration;
use lutra_control::client::{self, Client, Unavailable};
use lutra_control::rendezvous::{self, Instance};
use lutra_testkit::EngineBackend;
use serde_json::{Value, json};
const TIMEOUT: Duration = Duration::from_secs(10);
/// Starts a token listener for `backend` and writes its rendezvous file in
/// `dir`, as the desktop's claim does.
fn claim(dir: &Path, backend: Arc<EngineBackend>) -> Instance {
let token = rendezvous::new_token().unwrap();
let server = lutra_control::start_with_token(0, backend, &token).unwrap();
let instance = Instance {
port: server.local_addr().port(),
token,
pid: std::process::id(),
version: "test".into(),
};
rendezvous::write(dir, &instance).unwrap();
instance
}
/// Sends raw lines and reads one response line, or `None` at end of stream.
fn exchange(port: u16, lines: &[Value]) -> Vec<Option<Value>> {
let stream = TcpStream::connect(("127.0.0.1", port)).unwrap();
stream.set_read_timeout(Some(TIMEOUT)).unwrap();
let mut writer = stream.try_clone().unwrap();
let mut reader = BufReader::new(stream);
lines
.iter()
.map(|line| {
if writer.write_all(format!("{line}\n").as_bytes()).is_err() {
return None;
}
let mut text = String::new();
match reader.read_line(&mut text) {
Ok(0) | Err(_) => None,
Ok(_) => Some(serde_json::from_str(&text).unwrap()),
}
})
.collect()
}
#[test]
fn the_rendezvous_listener_needs_the_token_first() {
let dir = tempfile::tempdir().unwrap();
let instance = claim(dir.path(), Arc::new(EngineBackend::new()));
let ping = json!({"id": 2, "method": "app.ping"});
let r = exchange(instance.port, &[ping.clone(), ping.clone()]);
assert_eq!(r[0].as_ref().unwrap()["error"]["code"], "unauthorized");
assert!(r[1].is_none(), "the connection is closed");
let wrong = json!({"id": 1, "method": "app.auth", "params": {"token": "0".repeat(64)}});
let r = exchange(instance.port, &[wrong, ping.clone()]);
assert_eq!(r[0].as_ref().unwrap()["error"]["code"], "unauthorized");
assert!(r[1].is_none());
let r = exchange(instance.port, &[json!("garbage"), ping.clone()]);
assert_eq!(r[0].as_ref().unwrap()["error"]["code"], "unauthorized");
let right = json!({"id": 1, "method": "app.auth", "params": {"token": instance.token}});
let r = exchange(instance.port, &[right, ping]);
assert_eq!(r[0].as_ref().unwrap()["result"]["authenticated"], true);
assert_eq!(r[1].as_ref().unwrap()["result"]["pong"], true);
}
#[test]
fn the_open_control_channel_still_needs_no_token() {
let server = lutra_control::start(0, Arc::new(EngineBackend::new())).unwrap();
let mut client = Client::connect(server.local_addr().port(), TIMEOUT).unwrap();
assert_eq!(
client.request("app.ping", Value::Null).unwrap()["pong"],
true
);
}
#[test]
fn stale_files_are_detected() {
let dir = tempfile::tempdir().unwrap();
assert!(matches!(
client::connect_live(dir.path(), TIMEOUT),
Err(Unavailable::Missing)
));
std::fs::write(rendezvous::path(dir.path()), "{").unwrap();
assert!(matches!(
client::connect_live(dir.path(), TIMEOUT),
Err(Unavailable::Stale(_))
));
let closed = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
let port = closed.local_addr().unwrap().port();
drop(closed);
let dead = Instance {
port,
token: "t".into(),
pid: 1,
version: "old".into(),
};
rendezvous::write(dir.path(), &dead).unwrap();
assert!(matches!(
client::connect_live(dir.path(), TIMEOUT),
Err(Unavailable::Stale(_))
));
let live = claim(dir.path(), Arc::new(EngineBackend::new()));
let reused = Instance {
token: "f".repeat(64),
..live.clone()
};
rendezvous::write(dir.path(), &reused).unwrap();
assert!(
matches!(
client::connect_live(dir.path(), TIMEOUT),
Err(Unavailable::Stale(_))
),
"a listener that refuses the token is not ours"
);
rendezvous::write(dir.path(), &live).unwrap();
let (found, _) = client::connect_live(dir.path(), TIMEOUT).unwrap();
assert_eq!(found, live, "the stale file was replaced");
}
#[test]
fn a_second_start_forwards_folders_and_files() {
let rv = tempfile::tempdir().unwrap();
let project = tempfile::tempdir().unwrap();
let other = tempfile::tempdir().unwrap();
let file = project.path().join("a.php");
std::fs::write(&file, "<?php\necho 1;\n").unwrap();
let outside = other.path().join("b.php");
std::fs::write(&outside, "<?php\n").unwrap();
let backend = Arc::new(EngineBackend::new());
claim(rv.path(), Arc::clone(&backend));
let (_, mut second) = client::connect_live(rv.path(), TIMEOUT).unwrap();
let opened = second.open_file(&file).unwrap();
assert_eq!(opened.path, "a.php");
let root = backend
.engine
.lock()
.unwrap()
.state()
.project
.as_ref()
.map(|w| w.project.root().to_path_buf());
assert!(root.is_some(), "the file's folder became the project");
let again = second.open_file(&file).unwrap();
assert_eq!(again.id, opened.id, "an open file is focused, not reopened");
let refused = second.open_file(&outside).unwrap_err();
assert_eq!(refused.code(), Some("failed"));
second.open_folder(other.path()).unwrap();
let opened = second.open_file(&outside).unwrap();
assert_eq!(opened.path, "b.php");
assert_eq!(
second.focus().unwrap_err().code(),
Some("focus_failed"),
"the test backend has no window"
);
}
#[test]
fn reveal_waits_for_the_window_and_sends_zero_based_positions() {
let rv = tempfile::tempdir().unwrap();
let project = tempfile::tempdir().unwrap();
let file = project.path().join("a.php");
std::fs::write(&file, "<?php\n").unwrap();
let backend = Arc::new(EngineBackend::new());
claim(rv.path(), Arc::clone(&backend));
let (_, mut client) = client::connect_live(rv.path(), TIMEOUT).unwrap();
let opened = client.open_file(&file).unwrap();
let early = client.reveal(&opened.path, 0, 0, Duration::from_millis(300));
assert_eq!(early.unwrap_err().code(), Some("unknown_command"));
client
.execute(
"ui.registerCommands",
json!({"commands": [{"id": "editor.reveal", "labelKey": "command.editor.reveal"}]}),
)
.unwrap();
client.subscribe().unwrap();
client.reveal(&opened.path, 9, 4, TIMEOUT).unwrap();
loop {
let event = client.next_event(Some(TIMEOUT)).unwrap().unwrap();
if event["kind"] == "uiCommand" {
assert_eq!(event["id"], "editor.reveal");
assert_eq!(
event["params"],
json!({"path": "a.php", "line": 9, "column": 4})
);
break;
}
}
}