Lutra/crates/lsp/src/server.rs
danny ebbc89832c F3: suspended Phpactor start, ConPTY shell in a job, cancel superseded completions, syntax proptest
- lutra_proc::spawn_suspended: CREATE_SUSPENDED, join the kill-on-close
  job, resume via a Tool Help thread snapshot. Opt-in for long-lived
  children (Phpactor); git, php -l and the probe keep spawn because the
  snapshot costs ~60 ms per start.
- lutra_proc::adopt + Guard (Windows): the terminal's ConPTY shell joins a
  job, so processes it started end with the tab or with Lutra.
- lsp.completion cancels the previous pending completion on the same
  server ($/cancelRequest); the cancelled command resolves empty.
- Syntax proptests compare leaf kinds, outline and folding instead of the
  S-expression (tree-sitter-php 0.25.1 keeps a union_type wrapper after
  an undo); Malte's seed added.
- docs/development.md: data dirs, target dir inside the repo, parallel
  builds, deleting ui/node_modules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 17:28:54 +01:00

1511 lines
52 KiB
Rust

//! 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
/// (<https://learn.microsoft.com/windows/win32/procthread/process-creation-flags>).
#[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<Value>,
/// 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<dyn FnOnce(Result<Value, LspError>) + 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<Instant>,
/// The process generation it was sent to; `None` while queued.
sent_in: Option<u64>,
/// The encoded frame while queued.
unsent: Option<Vec<u8>>,
/// Receives the outcome.
reply: Reply,
}
/// What started the server, kept for restarts.
struct Launch {
/// The executable.
command: OsString,
/// Its arguments.
args: Vec<OsString>,
/// 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<Sender<Vec<u8>>>,
/// 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<i64, Pending>,
/// Ids of queued (not yet sent) requests, oldest first.
queue: VecDeque<i64>,
/// Open documents by URI.
documents: HashMap<String, Document>,
/// 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<u8>) -> 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<State>,
/// The event channel.
events: SyncSender<ServerEvent>,
/// 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<RequestId, LspError> {
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<Pending> {
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<Pending> = {
let mut state = self.lock();
let ids: Vec<i64> = 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<Pending> = {
let mut state = self.lock();
let ids: Vec<i64> = 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<Child, LspError> {
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<Self>, 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::<Vec<u8>>();
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<Self>, 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<Self>, 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<Value, LspError>) {
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<Shared>, first: Child) {
let mut first = Some(first);
let mut crashes: VecDeque<Instant> = 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<Vec<u8>>) {
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<Shared>,
generation: u64,
stdout: std::process::ChildStdout,
writer: Sender<Vec<u8>>,
) {
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<Vec<u8>>) {
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, &params);
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<Value, jsonrpc::ResponseError> {
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(&params) {
Some(diagnostics) => ServerEvent::Diagnostics(diagnostics),
None => ServerEvent::ProtocolError("malformed publishDiagnostics params".to_string()),
},
"window/logMessage" => ServerEvent::LogMessage {
level: MessageLevel::from_params(&params),
message: message_text(&params),
},
"window/showMessage" => ServerEvent::ShowMessage {
level: MessageLevel::from_params(&params),
message: message_text(&params),
},
"$/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<Shared>, 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<Result<Value, LspError>>,
/// The client, for cancelling.
shared: Weak<Shared>,
}
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<Value, LspError> {
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<Result<Value, LspError>> {
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<Result<Value, LspError>> {
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<Shared>,
/// The supervisor thread.
supervisor: Option<JoinHandle<()>>,
}
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<I, S>(
command: impl AsRef<OsStr>,
args: I,
root: &Path,
options: ServerOptions,
) -> Result<(Self, Receiver<ServerEvent>), LspError>
where
I: IntoIterator<Item = S>,
S: AsRef<OsStr>,
{
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<ServerCapabilities> {
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<RequestHandle, LspError> {
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<RequestHandle, LspError> {
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<dyn FnOnce(Result<Value, LspError>) + Send>,
) -> Result<RequestId, LspError> {
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<RequestHandle, LspError> {
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<RequestHandle, LspError> {
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<RequestHandle, LspError> {
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<RequestHandle, LspError> {
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<RequestHandle, LspError> {
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<RequestHandle, LspError> {
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<RequestHandle, LspError> {
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<RequestHandle, LspError> {
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<i32, LspError> {
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<i32, LspError> {
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<i32, LspError> {
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<i32> {
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<String> {
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();
}
}