//! A supervised language server process and its public client API. //! //! [`Server::spawn`] starts the process and a supervisor thread and returns //! at once; `initialize`/`initialized` run in the background and the //! [`Status`] moves from `Starting` to `Ready`. Requests sent before the //! server is ready are queued and sent once it is; document operations //! always update the client's copy and reach the server when it is ready, //! so a caller never has to wait for the server. //! //! Threads per server process: a writer (the only one touching stdin), a //! reader (frames from stdout, answers server requests, delivers responses //! and notifications), a stderr drain, plus one supervisor per [`Server`] //! that watches the process, expires timeouts, restarts after a crash and //! runs the shutdown. There is no async runtime: a server is a handful of //! blocking pipes, and threads with channels keep the library usable from //! the engine's synchronous pump without pulling an executor into L3. use std::collections::{HashMap, VecDeque}; use std::ffi::{OsStr, OsString}; use std::io::{BufReader, Write}; use std::panic::{AssertUnwindSafe, catch_unwind}; use std::path::{Path, PathBuf}; use std::process::{ChildStdin, Command, Stdio}; use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; use std::sync::mpsc::{self, Receiver, Sender, SyncSender, TrySendError}; use std::sync::{Arc, Mutex, MutexGuard, Weak}; use std::thread::{self, JoinHandle}; use std::time::{Duration, Instant}; use lutra_proc::Child; use lutra_text::{Buffer, Edit, Position}; use serde_json::{Value, json}; use crate::LspError; use crate::capabilities::{ServerCapabilities, SyncKind, client_capabilities}; use crate::documents::{Document, content_changes, text_document_item, text_document_position}; use crate::jsonrpc::{ self, Frame, MAX_MESSAGE_BYTES, METHOD_NOT_FOUND, Message, read_frame, truncate, }; use crate::types::PublishDiagnostics; use crate::uri::path_to_uri; /// How often the supervisor checks the process, timeouts and stop requests. const TICK: Duration = Duration::from_millis(20); /// The most requests waiting for an answer (sent or queued) per server. pub const MAX_PENDING: usize = 1024; /// The longest stderr line kept, in bytes. const MAX_STDERR_LINE: usize = 4096; /// The most items answered in one `workspace/configuration` request. const MAX_CONFIGURATION_ITEMS: usize = 1000; /// How long the shutdown waits for the process to exit after `exit`. const EXIT_GRACE: Duration = Duration::from_secs(1); /// Windows: the process gets no console window /// (). #[cfg(windows)] const CREATE_NO_WINDOW: u32 = 0x0800_0000; /// When a crashed server is restarted, and when the client gives up. #[derive(Debug, Clone, PartialEq, Eq)] pub struct RestartPolicy { /// The delay before the first restart; it doubles with every crash in /// the window (1 s, 2 s, 4 s, …). pub first_delay: Duration, /// The longest delay (30 s). pub max_delay: Duration, /// The number of crashes within [`Self::window`] after which the client /// stops restarting and reports [`Status::Failed`] (5). pub max_crashes: usize, /// The window crashes are counted in (2 min). pub window: Duration, } impl Default for RestartPolicy { fn default() -> Self { Self { first_delay: Duration::from_secs(1), max_delay: Duration::from_secs(30), max_crashes: 5, window: Duration::from_secs(120), } } } /// Options for [`Server::spawn`]. #[derive(Debug, Clone, PartialEq)] pub struct ServerOptions { /// The default timeout of requests (10 s). pub request_timeout: Duration, /// The timeout of `initialize` (30 s); a server that misses it counts /// as crashed. pub initialize_timeout: Duration, /// How long the shutdown waits for the `shutdown` response (2 s). pub shutdown_timeout: Duration, /// Restarts after crashes. pub restart: RestartPolicy, /// `initializationOptions` sent with `initialize`. pub initialization_options: Option, /// Extra environment variables for the process. pub env: Vec<(OsString, OsString)>, /// The capacity of the event channel; events beyond it are dropped and /// counted ([`Server::dropped_events`]). pub event_capacity: usize, } impl Default for ServerOptions { fn default() -> Self { Self { request_timeout: Duration::from_secs(10), initialize_timeout: Duration::from_secs(30), shutdown_timeout: Duration::from_secs(2), restart: RestartPolicy::default(), initialization_options: None, env: Vec::new(), event_capacity: 4096, } } } /// The state of a server. #[derive(Debug, Clone, PartialEq, Eq)] pub enum Status { /// The process runs and `initialize` is in flight. Starting, /// Initialized; requests and document sync reach the server. Ready, /// The process crashed and is restarted after `delay`. Restarting { /// Crashes within the restart window so far. crashes: usize, /// The delay before the next start. delay: Duration, /// Why the process was considered crashed (exit status, failed /// `initialize`, …). reason: String, }, /// The client gave up restarting (too many crashes in the window). Failed { /// The last crash reason. message: String, }, /// Shut down on request. Stopped, } /// The level of a `window/logMessage` or `window/showMessage`. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum MessageLevel { /// An error (1). Error, /// A warning (2). Warning, /// Information (3). Info, /// A log message (4), or an unknown level. Log, } impl MessageLevel { /// Maps the LSP `MessageType` number; unknown numbers become `Log`. fn from_params(params: &Value) -> Self { match params.get("type").and_then(Value::as_u64) { Some(1) => Self::Error, Some(2) => Self::Warning, Some(3) => Self::Info, _ => Self::Log, } } } /// Something the server or the client reports, delivered on the channel /// [`Server::spawn`] returns. #[derive(Debug, Clone, PartialEq)] pub enum ServerEvent { /// The status changed. Status(Status), /// `textDocument/publishDiagnostics`. Diagnostics(PublishDiagnostics), /// `window/logMessage`. LogMessage { /// The level. level: MessageLevel, /// The message (capped at 8 KiB). message: String, }, /// `window/showMessage` (and the text of `window/showMessageRequest`, /// which the client answers with `null`). ShowMessage { /// The level. level: MessageLevel, /// The message (capped at 8 KiB). message: String, }, /// `$/progress`. Progress { /// The progress token. token: Value, /// The progress value (`begin`, `report`, `end`). value: Value, }, /// Any other notification from the server. Notification { /// The method. method: String, /// The params. params: Value, }, /// A line the server wrote to stderr (capped at 4 KiB). Stderr(String), /// A message from the server that was dropped (malformed frame, invalid /// JSON, oversized, bad params), with the reason: the client's log line. ProtocolError(String), } /// The id of a request sent by the client. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)] pub struct RequestId(pub i64); /// A callback that receives a request's outcome, exactly once. type Reply = Box) + Send>; /// A request waiting for its answer. struct Pending { /// The method, for timeout errors. method: String, /// When it times out; `None` for never. deadline: Option, /// The process generation it was sent to; `None` while queued. sent_in: Option, /// The encoded frame while queued. unsent: Option>, /// Receives the outcome. reply: Reply, } /// What started the server, kept for restarts. struct Launch { /// The executable. command: OsString, /// Its arguments. args: Vec, /// The workspace root (also the working directory). root: PathBuf, /// The root as a URI. root_uri: String, } /// Mutable client state, behind one mutex. Every write to the server /// happens while holding it, so messages leave in the order the state /// changed. struct State { /// The current status. status: Status, /// Incremented for every process start and crash; responses and /// callbacks of older generations are ignored. generation: u64, /// The writer channel of the running process. writer: Option>>, /// Whether `initialize` succeeded for the current generation. ready: bool, /// The capabilities of the current generation. capabilities: ServerCapabilities, /// The next request id. next_id: i64, /// Requests waiting for an answer. pending: HashMap, /// Ids of queued (not yet sent) requests, oldest first. queue: VecDeque, /// Open documents by URI. documents: HashMap, /// Set by a shutdown request or the drop of the [`Server`]. stop_requested: bool, /// A failed `initialize` (generation, reason) for the supervisor. init_failure: Option<(u64, String)>, } impl State { /// Queues `frame` for the current process; `false` without one. fn write(&self, frame: Vec) -> bool { self.writer.as_ref().is_some_and(|w| w.send(frame).is_ok()) } /// Sends a notification to the current process. fn notify(&self, method: &str, params: Value) -> bool { self.write(jsonrpc::encode( &json!({"jsonrpc": "2.0", "method": method, "params": params}), )) } /// Whether messages reach an initialized server. fn live(&self) -> bool { self.ready && self.writer.is_some() } /// Whether the client accepts no more requests. fn closed(&self) -> bool { self.stop_requested || matches!(self.status, Status::Failed { .. } | Status::Stopped) } } /// State shared by the [`Server`] handle and its threads. struct Shared { /// The mutable state. state: Mutex, /// The event channel. events: SyncSender, /// Events dropped because the channel was full. dropped_events: AtomicUsize, /// The options. options: ServerOptions, /// How to start the process. launch: Launch, } impl Shared { /// Locks the state, recovering it if another thread panicked while /// holding the lock (the state stays consistent between statements, and /// a poisoned lock must not take the client down). fn lock(&self) -> MutexGuard<'_, State> { self.state .lock() .unwrap_or_else(std::sync::PoisonError::into_inner) } /// Delivers an event; a full channel drops it and counts the drop, a /// closed one (the receiver was dropped) ignores it on purpose. fn emit(&self, event: ServerEvent) { if let Err(TrySendError::Full(_)) = self.events.try_send(event) { self.dropped_events.fetch_add(1, Ordering::Relaxed); } } /// Sets the status and reports it. fn set_status(&self, state: &mut State, status: Status) { state.status = status.clone(); self.emit(ServerEvent::Status(status)); } /// Registers a request and sends it now, or queues it until the server /// is ready (`force` sends it to a process that is not yet initialized, /// for `initialize` and `shutdown`). /// /// # Errors /// [`LspError::Stopped`] once the client is closed (unless `force`), /// [`LspError::TooManyRequests`] at [`MAX_PENDING`]. fn submit( &self, state: &mut State, method: &str, params: Value, timeout: Duration, force: bool, reply: Reply, ) -> Result { if state.closed() && !force { return Err(LspError::Stopped); } if state.pending.len() >= MAX_PENDING { return Err(LspError::TooManyRequests { limit: MAX_PENDING }); } let id = state.next_id; state.next_id = state.next_id.saturating_add(1); let frame = jsonrpc::encode( &json!({"jsonrpc": "2.0", "id": id, "method": method, "params": params}), ); let mut pending = Pending { method: method.to_string(), deadline: Instant::now().checked_add(timeout), sent_in: None, unsent: None, reply, }; if (force && state.writer.is_some()) || state.live() { state.write(frame); pending.sent_in = Some(state.generation); } else { pending.unsent = Some(frame); state.queue.push_back(id); } state.pending.insert(id, pending); Ok(RequestId(id)) } /// Removes a pending request, sending `$/cancelRequest` if the current /// process has it. fn take_pending(&self, state: &mut State, id: i64, cancel: bool) -> Option { let pending = state.pending.remove(&id)?; if pending.sent_in.is_some() && pending.sent_in == Some(state.generation) && cancel { state.notify("$/cancelRequest", json!({"id": id})); } if pending.unsent.is_some() { state.queue.retain(|queued| *queued != id); } Some(pending) } /// Fails expired requests with [`LspError::Timeout`]. fn expire(&self) { let now = Instant::now(); let expired: Vec = { let mut state = self.lock(); let ids: Vec = state .pending .iter() .filter(|(_, p)| p.deadline.is_some_and(|d| d <= now)) .map(|(id, _)| *id) .collect(); ids.into_iter() .filter_map(|id| self.take_pending(&mut state, id, true)) .collect() }; for pending in expired { let method = pending.method; deliver(pending.reply, Err(LspError::Timeout { method })); } } /// Fails every pending request matching `filter` with `error`. fn fail_pending(&self, error: &LspError, filter: impl Fn(&Pending) -> bool) { let failed: Vec = { let mut state = self.lock(); let ids: Vec = state .pending .iter() .filter(|(_, p)| filter(p)) .map(|(id, _)| *id) .collect(); ids.into_iter() .filter_map(|id| self.take_pending(&mut state, id, false)) .collect() }; for pending in failed { deliver(pending.reply, Err(error.clone())); } } /// Handles a successful `initialize` of generation `generation`: sends /// `initialized`, (re)opens every document, sends queued requests and /// reports [`Status::Ready`]. fn on_initialized(&self, generation: u64, result: &Value) { let mut state = self.lock(); if state.generation != generation || state.stop_requested { return; } let capabilities = ServerCapabilities::from_json(result.get("capabilities").unwrap_or(&Value::Null)); if let Some(encoding) = &capabilities.position_encoding && encoding != "utf-16" { self.emit(ServerEvent::ProtocolError(format!( "server chose position encoding {encoding:?}; the client uses utf-16" ))); } state.ready = true; state.notify("initialized", json!({})); if capabilities.open_close { for (uri, document) in &state.documents { state.notify("textDocument/didOpen", text_document_item(uri, document)); } } state.capabilities = capabilities; while let Some(id) = state.queue.pop_front() { let frame = state.pending.get_mut(&id).and_then(|p| { p.sent_in = Some(generation); p.unsent.take() }); if let Some(frame) = frame { state.write(frame); } } self.set_status(&mut state, Status::Ready); } /// Starts the server process with piped stdio and no console window, /// in a [`lutra_proc`] group, so it and everything it starts die with /// Lutra even when Lutra is killed. /// /// # Errors /// [`LspError::Spawn`] when the executable cannot be started. fn start_process(&self) -> Result { let mut command = Command::new(&self.launch.command); command .args(&self.launch.args) .current_dir(&self.launch.root) .stdin(Stdio::piped()) .stdout(Stdio::piped()) .stderr(Stdio::piped()); for (key, value) in &self.options.env { command.env(key, value); } #[cfg(windows)] { use std::os::windows::process::CommandExt; command.creation_flags(CREATE_NO_WINDOW); } lutra_proc::spawn_suspended(command).map_err(|error| LspError::Spawn { command: self.launch.command.to_string_lossy().into_owned(), detail: error.to_string(), }) } /// Starts the I/O threads for `child` as a new generation and sends /// `initialize`. /// /// # Errors /// A reason when the pipes are missing or a thread cannot be started; /// the caller kills the process and counts it as a crash. fn attach(self: &Arc, child: &mut Child) -> Result<(), String> { let stdin = child.stdin.take().ok_or("no stdin pipe")?; let stdout = child.stdout.take().ok_or("no stdout pipe")?; let stderr = child.stderr.take().ok_or("no stderr pipe")?; let generation = { let mut state = self.lock(); state.generation = state.generation.saturating_add(1); state.ready = false; state.writer = None; state.generation }; let (writer, frames) = mpsc::channel::>(); let spawn_error = |error: std::io::Error| format!("cannot start a thread: {error}"); thread::Builder::new() .name("lsp-writer".into()) .spawn(move || write_loop(stdin, frames)) .map_err(spawn_error)?; let weak = Arc::downgrade(self); let reply_writer = writer.clone(); thread::Builder::new() .name("lsp-reader".into()) .spawn(move || read_loop(weak, generation, stdout, reply_writer)) .map_err(spawn_error)?; let weak = Arc::downgrade(self); thread::Builder::new() .name("lsp-stderr".into()) .spawn(move || stderr_loop(weak, stderr)) .map_err(spawn_error)?; let mut state = self.lock(); state.writer = Some(writer); self.set_status(&mut state, Status::Starting); let weak = Arc::downgrade(self); let reply: Reply = Box::new(move |result| { let Some(shared) = weak.upgrade() else { return; }; match result { Ok(value) => shared.on_initialized(generation, &value), Err(LspError::ServerCrashed | LspError::Stopped) => {} Err(error) => { shared.lock().init_failure = Some((generation, format!("initialize failed: {error}"))); } } }); let params = self.initialize_params(); let timeout = self.options.initialize_timeout; self.submit(&mut state, "initialize", params, timeout, true, reply) .map(|_| ()) .map_err(|error| error.to_string()) } /// The params of `initialize`. fn initialize_params(&self) -> Value { let root = &self.launch.root; let name = root .file_name() .map(|n| n.to_string_lossy().into_owned()) .unwrap_or_else(|| root.display().to_string()); let mut params = json!({ "processId": std::process::id(), "clientInfo": {"name": "Lutra", "version": env!("CARGO_PKG_VERSION")}, "locale": "en", "rootPath": root.display().to_string(), "rootUri": self.launch.root_uri, "workspaceFolders": [{"uri": self.launch.root_uri, "name": name}], "capabilities": client_capabilities(), "trace": "off", }); if let (Some(options), Some(object)) = (&self.options.initialization_options, params.as_object_mut()) { object.insert("initializationOptions".to_string(), options.clone()); } params } /// Watches one process until it exits, fails to initialize, or a stop /// is requested; expires timeouts meanwhile. fn run_generation(self: &Arc, child: &mut Child) -> Exit { if let Err(reason) = self.attach(child) { kill(child); return Exit::Crashed(reason); } let generation = self.lock().generation; loop { self.expire(); match child.try_wait() { Ok(Some(status)) => return Exit::Crashed(format!("server exited ({status})")), Ok(None) => {} Err(error) => { kill(child); return Exit::Crashed(format!("cannot watch the server process: {error}")); } } let (stop, failure) = { let mut state = self.lock(); let failure = match &state.init_failure { Some((g, _)) if *g == generation => state.init_failure.take(), _ => None, }; (state.stop_requested, failure) }; if stop { self.stop_process(child); return Exit::Stopped; } if let Some((_, reason)) = failure { kill(child); return Exit::Crashed(reason); } thread::sleep(TICK); } } /// Shuts the process down: `shutdown` (if initialized, waiting up to the /// shutdown timeout), `exit`, then a kill if it is still running after /// [`EXIT_GRACE`]. fn stop_process(self: &Arc, child: &mut Child) { let acknowledged = Arc::new(AtomicBool::new(false)); let sent = { let mut state = self.lock(); if state.live() { let flag = Arc::clone(&acknowledged); let reply: Reply = Box::new(move |_| flag.store(true, Ordering::Release)); let timeout = self.options.shutdown_timeout; self.submit(&mut state, "shutdown", Value::Null, timeout, true, reply) .is_ok() } else { false } }; if sent { let until = Instant::now().checked_add(self.options.shutdown_timeout); while !acknowledged.load(Ordering::Acquire) && until.is_some_and(|u| Instant::now() < u) && matches!(child.try_wait(), Ok(None)) { self.expire(); thread::sleep(TICK); } } { let mut state = self.lock(); state.notify("exit", Value::Null); state.ready = false; state.writer = None; state.generation = state.generation.saturating_add(1); } let until = Instant::now().checked_add(EXIT_GRACE); while until.is_some_and(|u| Instant::now() < u) && matches!(child.try_wait(), Ok(None)) { thread::sleep(TICK); } kill(child); } /// Records a crash: invalidates the generation and fails the requests /// that were sent to it with [`LspError::ServerCrashed`]; queued /// requests wait for the restart. fn on_crash(&self) { { let mut state = self.lock(); state.generation = state.generation.saturating_add(1); state.ready = false; state.writer = None; state.capabilities = ServerCapabilities::default(); } self.fail_pending(&LspError::ServerCrashed, |p| p.sent_in.is_some()); } /// Waits `delay` while expiring timeouts. /// /// # Returns /// `false` when a stop was requested meanwhile. fn wait_restart(&self, delay: Duration) -> bool { let until = Instant::now().checked_add(delay); loop { if self.lock().stop_requested { return false; } if until.is_none_or(|u| Instant::now() >= u) { return true; } self.expire(); thread::sleep(TICK); } } /// Ends the client: fails what is left with [`LspError::Stopped`] and /// reports `status`. fn finish(&self, status: Status) { { let mut state = self.lock(); state.ready = false; state.writer = None; self.set_status(&mut state, status); } self.fail_pending(&LspError::Stopped, |_| true); } } /// How one process generation ended. enum Exit { /// Stopped on request. Stopped, /// Crashed, failed to start or to initialize. Crashed(String), } /// Kills and reaps a process and everything in its group. Errors are /// ignored on purpose: the process may have exited already, and there is /// nothing else to do about it. fn kill(child: &mut Child) { let _ = child.kill_and_wait(); } /// Calls a reply outside any lock. A panicking callback is caught so it /// cannot take a reader or supervisor thread down; the caller's bug only /// loses that one reply. fn deliver(reply: Reply, result: Result) { let _ = catch_unwind(AssertUnwindSafe(move || reply(result))); } /// The supervisor: runs process generations, restarts after crashes with /// backoff, gives up after too many crashes in the window, and finishes /// with [`Status::Stopped`] or [`Status::Failed`]. fn supervise(shared: Arc, first: Child) { let mut first = Some(first); let mut crashes: VecDeque = VecDeque::new(); loop { let child = match first.take() { Some(child) => Ok(child), None => shared.start_process(), }; let exit = match child { Ok(mut child) => shared.run_generation(&mut child), Err(error) => Exit::Crashed(error.to_string()), }; let reason = match exit { Exit::Stopped => return shared.finish(Status::Stopped), Exit::Crashed(reason) => reason, }; shared.on_crash(); let now = Instant::now(); crashes.push_back(now); let policy = &shared.options.restart; while crashes .front() .is_some_and(|t| now.duration_since(*t) > policy.window) { crashes.pop_front(); } if crashes.len() >= policy.max_crashes { return shared.finish(Status::Failed { message: reason }); } let exponent = u32::try_from(crashes.len().saturating_sub(1)) .unwrap_or(u32::MAX) .min(16); let delay = policy .first_delay .saturating_mul(1u32 << exponent) .min(policy.max_delay); { let mut state = shared.lock(); if state.stop_requested { drop(state); return shared.finish(Status::Stopped); } let status = Status::Restarting { crashes: crashes.len(), delay, reason, }; shared.set_status(&mut state, status); } if !shared.wait_restart(delay) { return shared.finish(Status::Stopped); } } } /// Writes queued frames to the server's stdin until the channel closes or a /// write fails (the process exited; the supervisor notices that itself). fn write_loop(mut stdin: ChildStdin, frames: Receiver>) { for frame in frames { if stdin .write_all(&frame) .and_then(|()| stdin.flush()) .is_err() { return; } } } /// Reads frames from the server's stdout until it closes, and dispatches /// them. Malformed frames and messages are reported as /// [`ServerEvent::ProtocolError`] and skipped. fn read_loop( shared: Weak, generation: u64, stdout: std::process::ChildStdout, writer: Sender>, ) { let mut reader = BufReader::with_capacity(64 * 1024, stdout); loop { let frame = match read_frame(&mut reader, MAX_MESSAGE_BYTES) { Ok(Some(frame)) => frame, Ok(None) | Err(_) => return, }; let Some(shared) = shared.upgrade() else { return; }; match frame { Frame::Dropped(reason) => shared.emit(ServerEvent::ProtocolError(reason)), Frame::Body(body) => match Message::parse(&body) { Ok(message) => dispatch(&shared, generation, message, &writer), Err(reason) => shared.emit(ServerEvent::ProtocolError(reason)), }, } } } /// Handles one message from the server. fn dispatch(shared: &Shared, generation: u64, message: Message, writer: &Sender>) { match message { Message::Response { id, result } => { let Some(id) = id.as_i64() else { shared.emit(ServerEvent::ProtocolError(format!( "response with unknown id {id}" ))); return; }; let pending = { let mut state = shared.lock(); match state.pending.get(&id) { Some(p) if p.sent_in == Some(generation) => state.pending.remove(&id), _ => None, } }; if let Some(pending) = pending { let result = result.map_err(|error| LspError::Response { code: error.code, message: error.message, data: error.data, }); deliver(pending.reply, result); } } Message::Request { id, method, params } => { let result = answer_server_request(shared, &method, ¶ms); let response = Message::Response { id, result }; let _ = writer.send(jsonrpc::encode(&response.to_json())); } Message::Notification { method, params } => { shared.emit(notification_event(method, params)); } } } /// The client's answer to a request from the server. /// /// `workspace/configuration` gets one `null` per item (the server uses its /// defaults); progress creation and capability (un)registration are /// acknowledged; `window/showMessageRequest` is shown as a message and /// answered with `null` (no action chosen); `workspace/workspaceFolders` /// returns the root. Everything else is `MethodNotFound`. fn answer_server_request( shared: &Shared, method: &str, params: &Value, ) -> Result { match method { "workspace/configuration" => { let count = params .get("items") .and_then(Value::as_array) .map_or(0, Vec::len) .min(MAX_CONFIGURATION_ITEMS); Ok(Value::Array(vec![Value::Null; count])) } "window/workDoneProgress/create" | "client/registerCapability" | "client/unregisterCapability" => Ok(Value::Null), "window/showMessageRequest" => { shared.emit(ServerEvent::ShowMessage { level: MessageLevel::from_params(params), message: message_text(params), }); Ok(Value::Null) } "workspace/workspaceFolders" => { let name = shared .launch .root .file_name() .map(|n| n.to_string_lossy().into_owned()) .unwrap_or_default(); Ok(json!([{"uri": shared.launch.root_uri, "name": name}])) } _ => Err(jsonrpc::ResponseError { code: METHOD_NOT_FOUND, message: format!("unsupported method {}", truncate(method, 200)), data: None, }), } } /// The `message` member of a log or show message, capped. fn message_text(params: &Value) -> String { params .get("message") .and_then(Value::as_str) .map(|m| truncate(m, 8 * 1024)) .unwrap_or_default() } /// Maps a server notification to an event. fn notification_event(method: String, params: Value) -> ServerEvent { match method.as_str() { "textDocument/publishDiagnostics" => match PublishDiagnostics::from_json(¶ms) { Some(diagnostics) => ServerEvent::Diagnostics(diagnostics), None => ServerEvent::ProtocolError("malformed publishDiagnostics params".to_string()), }, "window/logMessage" => ServerEvent::LogMessage { level: MessageLevel::from_params(¶ms), message: message_text(¶ms), }, "window/showMessage" => ServerEvent::ShowMessage { level: MessageLevel::from_params(¶ms), message: message_text(¶ms), }, "$/progress" => ServerEvent::Progress { token: params.get("token").cloned().unwrap_or(Value::Null), value: params.get("value").cloned().unwrap_or(Value::Null), }, _ => ServerEvent::Notification { method, params }, } } /// Forwards the server's stderr line by line (capped) until it closes. fn stderr_loop(shared: Weak, stderr: std::process::ChildStderr) { let mut reader = BufReader::new(stderr); while let Ok(Some((line, _))) = jsonrpc::read_line_capped(&mut reader, MAX_STDERR_LINE) { let Some(shared) = shared.upgrade() else { return; }; shared.emit(ServerEvent::Stderr( String::from_utf8_lossy(&line).into_owned(), )); } } /// The receiving end of one request: wait for it, poll it or cancel it. /// /// Every request resolves exactly once: with the result, the server's /// error, a timeout, a cancel, a crash or the stop of the client. pub struct RequestHandle { /// The request id. id: RequestId, /// Receives the outcome. outcome: Receiver>, /// The client, for cancelling. shared: Weak, } impl RequestHandle { /// The request id. pub fn id(&self) -> RequestId { self.id } /// Blocks until the request resolves. Do not call this under the engine /// lock; the request's timeout bounds the wait. /// /// # Errors /// The request's failure; [`LspError::Stopped`] if the client went away. pub fn wait(&self) -> Result { self.outcome.recv().unwrap_or(Err(LspError::Stopped)) } /// Waits at most `timeout`; `None` if the request is still running. pub fn wait_timeout(&self, timeout: Duration) -> Option> { match self.outcome.recv_timeout(timeout) { Ok(result) => Some(result), Err(mpsc::RecvTimeoutError::Timeout) => None, Err(mpsc::RecvTimeoutError::Disconnected) => Some(Err(LspError::Stopped)), } } /// The outcome if it has arrived, without blocking. pub fn try_result(&self) -> Option> { match self.outcome.try_recv() { Ok(result) => Some(result), Err(mpsc::TryRecvError::Empty) => None, Err(mpsc::TryRecvError::Disconnected) => Some(Err(LspError::Stopped)), } } /// Cancels the request: it resolves with [`LspError::Cancelled`] and the /// server gets `$/cancelRequest`. /// /// # Returns /// `false` when it had already resolved. pub fn cancel(&self) -> bool { self.shared .upgrade() .is_some_and(|shared| cancel_request(&shared, self.id)) } } /// Cancels a pending request (see [`RequestHandle::cancel`]). fn cancel_request(shared: &Shared, id: RequestId) -> bool { let pending = { let mut state = shared.lock(); shared.take_pending(&mut state, id.0, true) }; match pending { Some(pending) => { deliver(pending.reply, Err(LspError::Cancelled)); true } None => false, } } /// A language server: a supervised process speaking LSP over stdio. /// /// Dropping it stops the server in the background; [`Server::shutdown`] /// stops it and waits. pub struct Server { /// The shared client state. shared: Arc, /// The supervisor thread. supervisor: Option>, } impl Server { /// Starts `command args…` in `root` and initializes it in the /// background. /// /// # Returns /// The server and the receiver of its events (status changes, /// diagnostics, messages, progress, stderr lines, dropped messages). /// /// # Errors /// [`LspError::InvalidPath`] for a relative root, [`LspError::Spawn`] /// when the executable cannot be started, [`LspError::Internal`] when /// the supervisor thread cannot be started. pub fn spawn( command: impl AsRef, args: I, root: &Path, options: ServerOptions, ) -> Result<(Self, Receiver), LspError> where I: IntoIterator, S: AsRef, { let root_uri = path_to_uri(root)?; let (events, receiver) = mpsc::sync_channel(options.event_capacity.max(1)); let shared = Arc::new(Shared { state: Mutex::new(State { status: Status::Starting, generation: 0, writer: None, ready: false, capabilities: ServerCapabilities::default(), next_id: 1, pending: HashMap::new(), queue: VecDeque::new(), documents: HashMap::new(), stop_requested: false, init_failure: None, }), events, dropped_events: AtomicUsize::new(0), options, launch: Launch { command: command.as_ref().to_os_string(), args: args .into_iter() .map(|a| a.as_ref().to_os_string()) .collect(), root: root.to_path_buf(), root_uri, }, }); let child = shared.start_process()?; let slot = Arc::new(Mutex::new(Some(child))); let supervised = Arc::clone(&shared); let handed = Arc::clone(&slot); let supervisor = thread::Builder::new() .name("lsp-supervisor".into()) .spawn(move || { let child = handed .lock() .unwrap_or_else(std::sync::PoisonError::into_inner) .take(); if let Some(child) = child { supervise(supervised, child); } }); match supervisor { Ok(handle) => Ok(( Self { shared, supervisor: Some(handle), }, receiver, )), Err(error) => { let child = slot .lock() .unwrap_or_else(std::sync::PoisonError::into_inner) .take(); if let Some(mut child) = child { kill(&mut child); } Err(LspError::Internal { detail: format!("cannot start the supervisor thread: {error}"), }) } } } /// The current status. pub fn status(&self) -> Status { self.shared.lock().status.clone() } /// The server's capabilities while it is ready. pub fn capabilities(&self) -> Option { let state = self.shared.lock(); state.ready.then(|| state.capabilities.clone()) } /// Events dropped so far because the event channel was full. pub fn dropped_events(&self) -> usize { self.shared.dropped_events.load(Ordering::Relaxed) } /// Sends a request with the default timeout. /// /// # Errors /// See [`Server::request_with`]. pub fn request(&self, method: &str, params: Value) -> Result { self.request_timeout(method, params, self.shared.options.request_timeout) } /// Sends a request with its own timeout. /// /// # Errors /// See [`Server::request_with`]. pub fn request_timeout( &self, method: &str, params: Value, timeout: Duration, ) -> Result { let (sender, outcome) = mpsc::channel(); let reply: Reply = Box::new(move |result| { let _ = sender.send(result); }); let id = self.request_with(method, params, timeout, reply)?; Ok(RequestHandle { id, outcome, shared: Arc::downgrade(&self.shared), }) } /// Sends a request whose outcome goes to `callback`, called exactly /// once on a client thread (never under the client's lock). Before the /// server is ready the request is queued; the timeout counts from now. /// /// # Errors /// [`LspError::Stopped`] once the client is stopped or failed, /// [`LspError::TooManyRequests`] at [`MAX_PENDING`]; the callback is not /// called then. pub fn request_with( &self, method: &str, params: Value, timeout: Duration, callback: Box) + Send>, ) -> Result { let mut state = self.shared.lock(); self.shared .submit(&mut state, method, params, timeout, false, callback) } /// Cancels a request sent with [`Server::request_with`]. /// /// # Returns /// `false` when it had already resolved. pub fn cancel(&self, id: RequestId) -> bool { cancel_request(&self.shared, id) } /// Sends a notification if the server is ready. /// /// # Returns /// Whether it was sent; notifications are not queued. pub fn notify(&self, method: &str, params: Value) -> bool { let state = self.shared.lock(); state.live() && state.notify(method, params) } /// `textDocument/completion` at `position`; `trigger` is the character /// that triggered it, if any. /// /// # Errors /// See [`Server::request_with`]; [`LspError::InvalidPath`] for a /// relative path. pub fn completion( &self, path: &Path, position: Position, trigger: Option<&str>, ) -> Result { let mut params = text_document_position(&path_to_uri(path)?, position); let context = match trigger { Some(character) => json!({"triggerKind": 2, "triggerCharacter": character}), None => json!({"triggerKind": 1}), }; if let Some(object) = params.as_object_mut() { object.insert("context".to_string(), context); } self.request("textDocument/completion", params) } /// `textDocument/hover` at `position`. /// /// # Errors /// See [`Server::completion`]. pub fn hover(&self, path: &Path, position: Position) -> Result { self.position_request("textDocument/hover", path, position) } /// `textDocument/signatureHelp` at `position`. /// /// # Errors /// See [`Server::completion`]. pub fn signature_help( &self, path: &Path, position: Position, ) -> Result { self.position_request("textDocument/signatureHelp", path, position) } /// `textDocument/definition` at `position`; parse the result with /// [`crate::Location::list_from_json`]. /// /// # Errors /// See [`Server::completion`]. pub fn definition(&self, path: &Path, position: Position) -> Result { self.position_request("textDocument/definition", path, position) } /// `textDocument/references` at `position`; parse the result with /// [`crate::Location::list_from_json`]. /// /// # Errors /// See [`Server::completion`]. pub fn references( &self, path: &Path, position: Position, include_declaration: bool, ) -> Result { let mut params = text_document_position(&path_to_uri(path)?, position); if let Some(object) = params.as_object_mut() { object.insert( "context".to_string(), json!({"includeDeclaration": include_declaration}), ); } self.request("textDocument/references", params) } /// `textDocument/prepareRename` at `position`. /// /// # Errors /// See [`Server::completion`]. pub fn prepare_rename( &self, path: &Path, position: Position, ) -> Result { self.position_request("textDocument/prepareRename", path, position) } /// `textDocument/rename` at `position`; parse the result with /// [`crate::WorkspaceEdit::from_json`]. /// /// # Errors /// See [`Server::completion`]. pub fn rename( &self, path: &Path, position: Position, new_name: &str, ) -> Result { let mut params = text_document_position(&path_to_uri(path)?, position); if let Some(object) = params.as_object_mut() { object.insert("newName".to_string(), json!(new_name)); } self.request("textDocument/rename", params) } /// A request whose params are a document and a position. fn position_request( &self, method: &str, path: &Path, position: Position, ) -> Result { self.request( method, text_document_position(&path_to_uri(path)?, position), ) } /// Opens a document with `text` at version 1. It is sent now if the /// server is ready, otherwise when it becomes ready (and again after /// every restart). /// /// # Returns /// The version (1). /// /// # Errors /// [`LspError::InvalidPath`], [`LspError::AlreadyOpen`]. pub fn did_open(&self, path: &Path, language_id: &str, text: &str) -> Result { let uri = path_to_uri(path)?; let mut state = self.shared.lock(); if state.documents.contains_key(&uri) { return Err(LspError::AlreadyOpen { uri }); } let document = Document { language_id: language_id.to_string(), version: 1, buffer: Buffer::new(text), }; if state.live() && state.capabilities.open_close { state.notify("textDocument/didOpen", text_document_item(&uri, &document)); } state.documents.insert(uri, document); Ok(1) } /// Applies `edits` (byte ranges into the document's current text, as in /// [`lutra_text::Buffer::apply`]) and sends them as incremental changes, /// or as the whole text if the server wants full sync. An empty batch /// changes nothing. /// /// # Returns /// The new version. /// /// # Errors /// [`LspError::InvalidPath`], [`LspError::NotOpen`], and /// [`LspError::Text`] for edits that do not fit the client's copy (the /// copy is unchanged; resync with [`Server::did_change_full`]). pub fn did_change(&self, path: &Path, edits: &[Edit]) -> Result { let uri = path_to_uri(path)?; let mut state = self.shared.lock(); let state = &mut *state; let document = state .documents .get_mut(&uri) .ok_or_else(|| LspError::NotOpen { uri: uri.clone() })?; if edits.is_empty() { return Ok(document.version); } let changes = content_changes(&mut document.buffer, edits)?; document.version = document.version.saturating_add(1); let version = document.version; let live = state.ready && state.writer.is_some(); let changes = match state.capabilities.sync { SyncKind::Incremental => Value::Array(changes), SyncKind::Full => json!([{"text": document.buffer.text()}]), SyncKind::None => return Ok(version), }; if live { state.notify( "textDocument/didChange", json!({"textDocument": {"uri": uri, "version": version}, "contentChanges": changes}), ); } Ok(version) } /// Replaces the document's whole text and sends it as one change. /// /// # Returns /// The new version. /// /// # Errors /// [`LspError::InvalidPath`], [`LspError::NotOpen`]. pub fn did_change_full(&self, path: &Path, text: &str) -> Result { let uri = path_to_uri(path)?; let mut state = self.shared.lock(); let state = &mut *state; let document = state .documents .get_mut(&uri) .ok_or_else(|| LspError::NotOpen { uri: uri.clone() })?; document.buffer = Buffer::new(text); document.version = document.version.saturating_add(1); let version = document.version; if state.ready && state.writer.is_some() && state.capabilities.sync != SyncKind::None { state.notify( "textDocument/didChange", json!({"textDocument": {"uri": uri, "version": version}, "contentChanges": [{"text": text}]}), ); } Ok(version) } /// Sends `textDocument/didSave` (with the text if the server asks for /// it) when the server is ready and wants it. /// /// # Errors /// [`LspError::InvalidPath`], [`LspError::NotOpen`]. pub fn did_save(&self, path: &Path) -> Result<(), LspError> { let uri = path_to_uri(path)?; let state = self.shared.lock(); let document = state .documents .get(&uri) .ok_or_else(|| LspError::NotOpen { uri: uri.clone() })?; if state.live() && state.capabilities.save { let mut params = json!({"textDocument": {"uri": uri}}); if state.capabilities.save_include_text && let Some(object) = params.as_object_mut() { object.insert("text".to_string(), json!(document.buffer.text())); } state.notify("textDocument/didSave", params); } Ok(()) } /// Closes a document and sends `textDocument/didClose` when the server /// is ready. /// /// # Errors /// [`LspError::InvalidPath`], [`LspError::NotOpen`]. pub fn did_close(&self, path: &Path) -> Result<(), LspError> { let uri = path_to_uri(path)?; let mut state = self.shared.lock(); if state.documents.remove(&uri).is_none() { return Err(LspError::NotOpen { uri }); } if state.live() && state.capabilities.open_close { state.notify( "textDocument/didClose", json!({"textDocument": {"uri": uri}}), ); } Ok(()) } /// The version of an open document. pub fn document_version(&self, path: &Path) -> Option { let uri = path_to_uri(path).ok()?; self.shared.lock().documents.get(&uri).map(|d| d.version) } /// The client's copy of an open document's text. pub fn document_text(&self, path: &Path) -> Option { let uri = path_to_uri(path).ok()?; self.shared .lock() .documents .get(&uri) .map(|d| d.buffer.text()) } /// Stops the server (`shutdown`, `exit`, kill if needed) and waits for /// it: at most the shutdown timeout plus about a second. Pending /// requests fail with [`LspError::Stopped`]. Call it off the engine /// lock. pub fn shutdown(mut self) { self.request_stop(); if let Some(handle) = self.supervisor.take() { let _ = handle.join(); } } /// Asks the supervisor to stop. fn request_stop(&self) { self.shared.lock().stop_requested = true; } } impl Drop for Server { /// Requests a stop without waiting; the supervisor shuts the process /// down in the background. fn drop(&mut self) { self.request_stop(); } }