diff --git a/Cargo.lock b/Cargo.lock index fda53f2..2d94472 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2611,6 +2611,12 @@ dependencies = [ [[package]] name = "lutra-lsp" version = "0.0.0" +dependencies = [ + "lutra-text", + "proptest", + "serde_json", + "tempfile", +] [[package]] name = "lutra-mcp" diff --git a/crates/lsp/Cargo.toml b/crates/lsp/Cargo.toml index 16fd6fd..e636db5 100644 --- a/crates/lsp/Cargo.toml +++ b/crates/lsp/Cargo.toml @@ -11,7 +11,19 @@ publish.workspace = true [package.metadata.lutra] layer = 3 +[[bin]] +name = "lutra-lsp-fake" +path = "src/bin/lutra-lsp-fake.rs" +test = false +doc = false + [dependencies] +lutra-text.workspace = true +serde_json = "1.0.154" + +[dev-dependencies] +proptest.workspace = true +tempfile.workspace = true [lints] workspace = true diff --git a/crates/lsp/src/bin/lutra-lsp-fake.rs b/crates/lsp/src/bin/lutra-lsp-fake.rs new file mode 100644 index 0000000..4c561b5 --- /dev/null +++ b/crates/lsp/src/bin/lutra-lsp-fake.rs @@ -0,0 +1,303 @@ +//! A scripted fake language server for the `lutra-lsp` tests. +//! +//! Not shipped: the integration tests start it through +//! `CARGO_BIN_EXE_lutra-lsp-fake`. It speaks LSP over stdio with the +//! client's own framing and behaves predictably: +//! +//! - `initialize` announces incremental sync (`--sync-full` for full sync) +//! and save with text; `--exit-immediately` exits before reading anything, +//! `--init-error` answers `initialize` with an error. +//! - After `initialized` it sends three requests to the client +//! (`workspace/configuration` with two items, an unknown method, +//! `window/workDoneProgress/create`) and reports the answers as the +//! notification `fake/serverResponses`; it also logs `hello`. +//! - Every `didOpen`/`didChange` applies the change to its own copy and +//! publishes one diagnostic whose message is the whole text, with the +//! document version; `didClose` publishes no diagnostics; `didSave` sends +//! `fake/saved` with the text it received. +//! - Requests: `textDocument/hover` answers `hover L:C`, +//! `textDocument/definition` the same position, `fake/echo` its params, +//! `fake/error` an error, `fake/sleep` never answers until cancelled +//! (then `RequestCancelled` and the notification `fake/cancelled`), +//! `fake/crash` exits with code 7, `fake/garbage` writes malformed frames +//! before answering. `shutdown` answers `null`; `exit` exits with 0. + +use std::collections::HashMap; +use std::io::{self, BufReader, Write}; +use std::process::exit; + +use lutra_lsp::jsonrpc::{ + self, Frame, MAX_MESSAGE_BYTES, METHOD_NOT_FOUND, Message, REQUEST_CANCELLED, ResponseError, +}; +use lutra_lsp::types::position_from_json; +use lutra_text::{Buffer, ColumnUnit, Edit}; +use serde_json::{Value, json}; + +/// The fake server's state. +struct Fake { + /// Documents by URI. + documents: HashMap, + /// Ids of `fake/sleep` requests not yet cancelled. + sleeping: Vec, + /// Answers to the server's own requests, by id. + responses: Vec<(Value, Value)>, + /// Whether changes are full-text only. + full_sync: bool, + /// Whether `initialize` fails. + init_error: bool, +} + +/// Runs the fake server until `exit` or the end of stdin. +fn main() { + let args: Vec = std::env::args().skip(1).collect(); + if args.iter().any(|a| a == "--exit-immediately") { + exit(3); + } + let _ = writeln!(io::stderr(), "fake server started"); + let mut fake = Fake { + documents: HashMap::new(), + sleeping: Vec::new(), + responses: Vec::new(), + full_sync: args.iter().any(|a| a == "--sync-full"), + init_error: args.iter().any(|a| a == "--init-error"), + }; + let mut reader = BufReader::new(io::stdin().lock()); + while let Ok(Some(frame)) = jsonrpc::read_frame(&mut reader, MAX_MESSAGE_BYTES) { + let Frame::Body(body) = frame else { + continue; + }; + if let Ok(message) = Message::parse(&body) { + fake.handle(message); + } + } +} + +/// Writes one message to stdout; exits if stdout is gone. +fn send(value: &Value) { + let mut stdout = io::stdout().lock(); + if jsonrpc::write_frame(&mut stdout, value).is_err() { + exit(1); + } +} + +/// Writes raw bytes to stdout. +fn send_raw(bytes: &[u8]) { + let mut stdout = io::stdout().lock(); + if stdout + .write_all(bytes) + .and_then(|()| stdout.flush()) + .is_err() + { + exit(1); + } +} + +/// Sends a notification. +fn notify(method: &str, params: Value) { + send(&json!({"jsonrpc": "2.0", "method": method, "params": params})); +} + +/// Sends a response. +fn respond(id: Value, result: Result) { + send(&Message::Response { id, result }.to_json()); +} + +/// An error response body. +fn error(code: i64, message: &str) -> ResponseError { + ResponseError { + code, + message: message.to_string(), + data: None, + } +} + +impl Fake { + /// Handles one message from the client. + fn handle(&mut self, message: Message) { + match message { + Message::Request { id, method, params } => self.request(id, &method, ¶ms), + Message::Notification { method, params } => self.notification(&method, ¶ms), + Message::Response { id, result } => { + let value = match result { + Ok(value) => json!({"result": value}), + Err(e) => json!({"error": e.code}), + }; + self.responses.push((id, value)); + if self.responses.len() == 3 { + let all: Vec = self + .responses + .iter() + .map(|(id, value)| json!({"id": id, "answer": value})) + .collect(); + notify("fake/serverResponses", json!({"responses": all})); + } + } + } + } + + /// Answers a request. + fn request(&mut self, id: Value, method: &str, params: &Value) { + match method { + "initialize" if self.init_error => respond(id, Err(error(-32002, "no init"))), + "initialize" => { + let change = if self.full_sync { 1 } else { 2 }; + respond( + id, + Ok(json!({ + "capabilities": { + "positionEncoding": "utf-16", + "textDocumentSync": {"openClose": true, "change": change, "save": {"includeText": true}}, + "hoverProvider": true, + "definitionProvider": true + }, + "serverInfo": {"name": "fake"} + })), + ); + } + "shutdown" => respond(id, Ok(Value::Null)), + "textDocument/hover" => { + let position = at(params, "/position"); + respond( + id, + Ok( + json!({"contents": {"kind": "markdown", "value": format!("hover {}:{}", at(position, "/line"), at(position, "/character"))}}), + ), + ); + } + "textDocument/definition" => { + let uri = at(params, "/textDocument/uri").clone(); + let position = at(params, "/position").clone(); + respond( + id, + Ok(json!([{"uri": uri, "range": {"start": position, "end": position}}])), + ); + } + "fake/echo" => respond(id, Ok(params.clone())), + "fake/error" => respond(id, Err(error(-32001, "boom"))), + "fake/sleep" => self.sleeping.push(id), + "fake/crash" => exit(7), + "fake/garbage" => { + send_raw(b"garbage line\r\n\r\n"); + send_raw(b"Content-Length: 5\r\n\r\n{nope"); + send_raw(b"Content-Type: x\r\n\r\n"); + send_raw(b"Content-Length: 2\r\n\r\n[]"); + respond(id, Ok(json!("after garbage"))); + } + _ => respond(id, Err(error(METHOD_NOT_FOUND, "unknown"))), + } + } + + /// Handles a notification. + fn notification(&mut self, method: &str, params: &Value) { + let uri = at(params, "/textDocument/uri") + .as_str() + .unwrap_or_default() + .to_string(); + let version = at(params, "/textDocument/version").clone(); + match method { + "initialized" => { + send( + &json!({"jsonrpc": "2.0", "id": "c1", "method": "workspace/configuration", + "params": {"items": [{"section": "a"}, {"section": "b"}]}}), + ); + send(&json!({"jsonrpc": "2.0", "id": 2, "method": "fake/unknown", "params": {}})); + send( + &json!({"jsonrpc": "2.0", "id": 3, "method": "window/workDoneProgress/create", + "params": {"token": "t"}}), + ); + notify("window/logMessage", json!({"type": 3, "message": "hello"})); + } + "exit" => exit(0), + "$/cancelRequest" => { + let id = at(params, "/id").clone(); + if let Some(index) = self.sleeping.iter().position(|s| *s == id) { + self.sleeping.remove(index); + respond(id.clone(), Err(error(REQUEST_CANCELLED, "cancelled"))); + notify("fake/cancelled", json!({"id": id})); + } + } + "textDocument/didOpen" => { + let text = at(params, "/textDocument/text") + .as_str() + .unwrap_or_default(); + self.documents.insert(uri.clone(), Buffer::new(text)); + self.publish(&uri, version); + } + "textDocument/didChange" => { + let changes = at(params, "/contentChanges") + .as_array() + .cloned() + .unwrap_or_default(); + let outcome = self.apply(&uri, &changes); + match outcome { + Ok(()) => self.publish(&uri, version), + Err(message) => publish_text(&uri, version, &format!("ERROR: {message}")), + } + } + "textDocument/didSave" => { + notify( + "fake/saved", + json!({"uri": uri, "text": at(params, "/text")}), + ); + } + "textDocument/didClose" => { + self.documents.remove(&uri); + notify( + "textDocument/publishDiagnostics", + json!({"uri": uri, "diagnostics": []}), + ); + } + _ => {} + } + } + + /// Applies content changes one after another. + fn apply(&mut self, uri: &str, changes: &[Value]) -> Result<(), String> { + let buffer = self.documents.get_mut(uri).ok_or("not open")?; + for change in changes { + let text = at(change, "/text").as_str().ok_or("no text")?; + if change.get("range").is_none() { + *buffer = Buffer::new(text); + continue; + } + let start = position_from_json(at(change, "/range/start")).ok_or("bad start")?; + let end = position_from_json(at(change, "/range/end")).ok_or("bad end")?; + let start = buffer + .position_to_offset(start, ColumnUnit::Utf16) + .map_err(|e| e.to_string())?; + let end = buffer + .position_to_offset(end, ColumnUnit::Utf16) + .map_err(|e| e.to_string())?; + buffer + .apply(&[Edit::replace(start..end, text)]) + .map_err(|e| e.to_string())?; + } + Ok(()) + } + + /// Publishes the document's text as its one diagnostic. + fn publish(&self, uri: &str, version: Value) { + let text = self + .documents + .get(uri) + .map(Buffer::text) + .unwrap_or_default(); + publish_text(uri, version, &text); + } +} + +/// Publishes one diagnostic with `message`. +fn publish_text(uri: &str, version: Value, message: &str) { + notify( + "textDocument/publishDiagnostics", + json!({"uri": uri, "version": version, "diagnostics": [{ + "range": {"start": {"line": 0, "character": 0}, "end": {"line": 0, "character": 0}}, + "severity": 1, "source": "fake", "message": message + }]}), + ); +} + +/// The value at a JSON pointer, `null` when absent. +fn at<'a>(value: &'a Value, pointer: &str) -> &'a Value { + value.pointer(pointer).unwrap_or(&Value::Null) +} diff --git a/crates/lsp/src/capabilities.rs b/crates/lsp/src/capabilities.rs new file mode 100644 index 0000000..f58f410 --- /dev/null +++ b/crates/lsp/src/capabilities.rs @@ -0,0 +1,210 @@ +//! The client capabilities Lutra announces and the parts of the server's +//! capabilities the client acts on. +//! +//! Spec: . + +use serde_json::{Value, json}; + +/// The `capabilities` member of the `initialize` request. +/// +/// Announced: incremental document sync with `didSave`; completion (plain +/// text insert, no snippets, markdown or plain documentation); hover; +/// signature help; definition; references; rename with `prepareRename`; +/// `publishDiagnostics` with versions; `workspace/configuration` (answered +/// with `null` values) and workspace folders; work-done progress; and the +/// `utf-16` position encoding only. No dynamic registration and no +/// `workspace/applyEdit`: workspace edits come only as rename results. +pub fn client_capabilities() -> Value { + let documentation = json!(["markdown", "plaintext"]); + json!({ + "general": { + "positionEncodings": ["utf-16"] + }, + "textDocument": { + "synchronization": { + "dynamicRegistration": false, + "willSave": false, + "willSaveWaitUntil": false, + "didSave": true + }, + "completion": { + "dynamicRegistration": false, + "contextSupport": true, + "completionItem": { + "snippetSupport": false, + "documentationFormat": documentation, + "deprecatedSupport": true, + "labelDetailsSupport": true, + "insertReplaceSupport": false + } + }, + "hover": { + "dynamicRegistration": false, + "contentFormat": documentation + }, + "signatureHelp": { + "dynamicRegistration": false, + "contextSupport": true, + "signatureInformation": { + "documentationFormat": documentation, + "parameterInformation": {"labelOffsetSupport": true}, + "activeParameterSupport": true + } + }, + "definition": {"dynamicRegistration": false, "linkSupport": true}, + "references": {"dynamicRegistration": false}, + "rename": {"dynamicRegistration": false, "prepareSupport": true}, + "publishDiagnostics": { + "relatedInformation": false, + "versionSupport": true, + "codeDescriptionSupport": false, + "dataSupport": false + } + }, + "workspace": { + "applyEdit": false, + "configuration": true, + "workspaceFolders": true, + "didChangeConfiguration": {"dynamicRegistration": false} + }, + "window": { + "workDoneProgress": true, + "showMessage": {} + } + }) +} + +/// How the server wants document changes. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum SyncKind { + /// The server does not want `didChange` at all. + None, + /// Every change sends the whole text. + Full, + /// Changes are sent as ranges. + Incremental, +} + +/// The server capabilities the client acts on, plus the raw object. +#[derive(Debug, Clone, PartialEq)] +pub struct ServerCapabilities { + /// How `didChange` is sent. + pub sync: SyncKind, + /// Whether `didOpen`/`didClose` are sent. Servers that announce sync but + /// omit `openClose` get them anyway, as most servers expect. + pub open_close: bool, + /// Whether `didSave` is sent. + pub save: bool, + /// Whether `didSave` carries the text. + pub save_include_text: bool, + /// The encoding the server picked (`None`: the default, `utf-16`). + pub position_encoding: Option, + /// The whole `capabilities` object, for callers that check providers + /// (`completionProvider`, `renameProvider`, …). + pub raw: Value, +} + +impl Default for ServerCapabilities { + fn default() -> Self { + Self::from_json(&Value::Null) + } +} + +impl ServerCapabilities { + /// Reads the `capabilities` member of an `initialize` result. + /// + /// `textDocumentSync` may be a number (0, 1, 2) or an object; anything + /// else counts as [`SyncKind::Full`] with open/close, the safe choice. + pub fn from_json(value: &Value) -> Self { + let sync_value = value.get("textDocumentSync"); + let kind = |number: Option| match number { + Some(0) => SyncKind::None, + Some(2) => SyncKind::Incremental, + _ => SyncKind::Full, + }; + let (sync, open_close, save, save_include_text) = match sync_value { + Some(Value::Number(number)) => (kind(number.as_u64()), true, true, false), + Some(Value::Object(object)) => { + let save = object.get("save"); + ( + kind(object.get("change").and_then(Value::as_u64)), + object + .get("openClose") + .and_then(Value::as_bool) + .unwrap_or(true), + match save { + Some(Value::Bool(enabled)) => *enabled, + Some(Value::Object(_)) => true, + _ => false, + }, + save.and_then(|s| s.get("includeText")) + .and_then(Value::as_bool) + .unwrap_or(false), + ) + } + _ => (SyncKind::Full, true, true, false), + }; + Self { + sync, + open_close, + save, + save_include_text, + position_encoding: value + .get("positionEncoding") + .and_then(Value::as_str) + .map(str::to_string), + raw: value.clone(), + } + } + + /// Whether the server announces `provider` (e.g. `"hoverProvider"`): + /// present and not `false` or `null`. + pub fn supports(&self, provider: &str) -> bool { + !matches!( + self.raw.get(provider), + None | Some(Value::Null) | Some(Value::Bool(false)) + ) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn sync_forms() { + assert_eq!( + ServerCapabilities::from_json(&json!({"textDocumentSync": 2})).sync, + SyncKind::Incremental + ); + let object = ServerCapabilities::from_json(&json!({"textDocumentSync": { + "change": 2, "openClose": true, "save": {"includeText": true} + }})); + assert_eq!(object.sync, SyncKind::Incremental); + assert!(object.save && object.save_include_text); + let none = ServerCapabilities::from_json(&json!({"textDocumentSync": 0})); + assert_eq!(none.sync, SyncKind::None); + assert_eq!(ServerCapabilities::default().sync, SyncKind::Full); + } + + #[test] + fn supports_providers() { + let caps = ServerCapabilities::from_json( + &json!({"hoverProvider": true, "renameProvider": {"prepareProvider": true}, "x": false}), + ); + assert!(caps.supports("hoverProvider")); + assert!(caps.supports("renameProvider")); + assert!(!caps.supports("x")); + assert!(!caps.supports("definitionProvider")); + } + + #[test] + fn announces_utf16_and_incremental_basics() { + let caps = client_capabilities(); + assert_eq!(caps["general"]["positionEncodings"], json!(["utf-16"])); + assert_eq!( + caps["textDocument"]["rename"]["prepareSupport"], + json!(true) + ); + } +} diff --git a/crates/lsp/src/documents.rs b/crates/lsp/src/documents.rs new file mode 100644 index 0000000..73b2328 --- /dev/null +++ b/crates/lsp/src/documents.rs @@ -0,0 +1,175 @@ +//! The client's copy of every open document and the conversion of +//! `lutra_text` edits into LSP content changes. +//! +//! The client keeps each open document's text in a [`Buffer`] so it can +//! convert byte-range edits to UTF-16 positions, send the whole text when a +//! server wants full sync, and reopen every document after a restart. + +use lutra_text::{Buffer, ColumnUnit, Edit, TextError}; +use serde_json::{Value, json}; + +use crate::types::{Range, position_to_json}; + +/// One open document. +#[derive(Debug, Clone)] +pub(crate) struct Document { + /// The LSP language id (`php`, …). + pub language_id: String, + /// The version last sent (or to be sent on reopen); starts at 1. + pub version: i32, + /// The current text. + pub buffer: Buffer, +} + +/// Applies `edits` to `buffer` and returns the matching LSP +/// `TextDocumentContentChangeEvent`s (`{range, text}`, UTF-16 columns). +/// +/// `edits` follow [`Buffer::apply`]: every range refers to the text before +/// the call, in any order. LSP applies content changes one after another, +/// each against the result of the previous one, so: +/// +/// - Edits that touch (one ends where the next starts, including several +/// insertions at one offset) are merged into one change, their texts in +/// the order `Buffer::apply` uses. Otherwise a change could put a `\n` +/// right after a `\r` and move the line break under a position computed +/// for the next change. +/// - The merged changes are emitted from the end of the text to the start. +/// Each one then only changes text after every change still to come, with +/// at least one untouched character in between, so positions computed on +/// the old text stay valid. +/// +/// # Errors +/// The [`TextError`] of the first range that is not a valid position (inside +/// a character or a CRLF, past the end) or of a batch `Buffer::apply` +/// rejects; the buffer is unchanged then. +pub fn content_changes(buffer: &mut Buffer, edits: &[Edit]) -> Result, TextError> { + let mut resolved = Vec::with_capacity(edits.len()); + for edit in edits { + let start = buffer.offset_to_position(edit.range.start, ColumnUnit::Utf16)?; + let end = buffer.offset_to_position(edit.range.end, ColumnUnit::Utf16)?; + resolved.push((edit.range.clone(), Range { start, end }, edit.text.as_str())); + } + let mut updated = buffer.clone(); + updated.apply(edits)?; + *buffer = updated; + resolved.sort_by_key(|(bytes, _, _)| (bytes.start, bytes.end)); + let mut groups: Vec<(usize, Range, String)> = Vec::new(); + for (bytes, range, text) in resolved { + match groups.last_mut() { + Some((end, group, merged)) if *end == bytes.start => { + *end = bytes.end; + group.end = range.end; + merged.push_str(text); + } + _ => groups.push((bytes.end, range, text.to_string())), + } + } + Ok(groups + .into_iter() + .rev() + .map(|(_, range, text)| json!({"range": range.to_json(), "text": text})) + .collect()) +} + +/// The `TextDocumentItem` of a `didOpen`. +pub(crate) fn text_document_item(uri: &str, document: &Document) -> Value { + json!({ + "textDocument": { + "uri": uri, + "languageId": document.language_id, + "version": document.version, + "text": document.buffer.text(), + } + }) +} + +/// The params of a `textDocument/{definition, hover, …}` request. +pub(crate) fn text_document_position(uri: &str, position: lutra_text::Position) -> Value { + json!({"textDocument": {"uri": uri}, "position": position_to_json(position)}) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::types::position_from_json; + use proptest::prelude::*; + + /// Applies LSP content changes one after another, as a server does. + fn apply_sequentially(text: &str, changes: &[Value]) -> String { + let mut buffer = Buffer::new(text); + for change in changes { + let start = position_from_json(&change["range"]["start"]).unwrap(); + let end = position_from_json(&change["range"]["end"]).unwrap(); + let start = buffer.position_to_offset(start, ColumnUnit::Utf16).unwrap(); + let end = buffer.position_to_offset(end, ColumnUnit::Utf16).unwrap(); + let replacement = change["text"].as_str().unwrap(); + buffer + .apply(&[Edit::replace(start..end, replacement)]) + .unwrap(); + } + buffer.text() + } + + #[test] + fn utf16_columns_and_order() { + let mut buffer = Buffer::new("a😀b\r\nc"); + let changes = content_changes( + &mut buffer, + &[ + Edit::insert(0, "X"), + Edit::replace(5..6, "B"), + Edit::insert(9, "!"), + ], + ) + .unwrap(); + assert_eq!(buffer.text(), "Xa😀B\r\nc!"); + assert_eq!( + changes[0]["range"]["start"], + json!({"line": 1, "character": 1}) + ); + assert_eq!( + changes[1]["range"]["start"], + json!({"line": 0, "character": 3}) + ); + assert_eq!(apply_sequentially("a😀b\r\nc", &changes), buffer.text()); + } + + #[test] + fn rejects_bad_edits_unchanged() { + let mut buffer = Buffer::new("é"); + assert!(content_changes(&mut buffer, &[Edit::insert(1, "x")]).is_err()); + assert!(content_changes(&mut buffer, &[Edit::insert(9, "x")]).is_err()); + assert_eq!(buffer.text(), "é"); + } + + fn text_and_edits() -> impl Strategy)> { + "[a-c\u{e9}\u{1F600}\r\n]{0,24}".prop_flat_map(|text| { + let edits = proptest::collection::vec( + (0..=text.len(), 0..=4usize, "[x\u{1F600}\n\r]{0,3}"), + 0..5, + ); + (Just(text), edits) + }) + } + + proptest! { + #[test] + fn sequential_changes_match_apply((text, raw) in text_and_edits()) { + let mut buffer = Buffer::new(&text); + let edits: Vec = raw + .into_iter() + .map(|(start, len, insert)| Edit::replace(start..(start + len).min(text.len()), insert)) + .collect(); + let mut expected = Buffer::new(&text); + let applied = expected.apply(&edits); + match content_changes(&mut buffer, &edits) { + Ok(changes) => { + prop_assert!(applied.is_ok()); + prop_assert_eq!(buffer.text(), expected.text()); + prop_assert_eq!(apply_sequentially(&text, &changes), expected.text()); + } + Err(_) => prop_assert_eq!(buffer.text(), text), + } + } + } +} diff --git a/crates/lsp/src/error.rs b/crates/lsp/src/error.rs new file mode 100644 index 0000000..c1cf2ec --- /dev/null +++ b/crates/lsp/src/error.rs @@ -0,0 +1,105 @@ +//! Errors of the language server client. + +use std::fmt; + +use lutra_text::TextError; + +/// Why a client operation failed. +/// +/// Requests resolve to this when the server answers with an error, does not +/// answer in time, crashes or is stopped; document operations return it for +/// edits that do not fit the client's copy of the document. +#[derive(Debug, Clone, PartialEq)] +pub enum LspError { + /// The server process could not be started. + Spawn { + /// The command that failed to start. + command: String, + /// The operating system's error message. + detail: String, + }, + /// The server answered the request with a JSON-RPC error. + Response { + /// The JSON-RPC error code. + code: i64, + /// The server's error message (capped). + message: String, + /// The error's `data` member, if any. + data: Option, + }, + /// The server did not answer within the request's timeout; the client + /// sent `$/cancelRequest`. + Timeout { + /// The request's method. + method: String, + }, + /// The request was cancelled by the caller; the client sent + /// `$/cancelRequest`. + Cancelled, + /// The server process exited while the request was in flight. + ServerCrashed, + /// The client is stopped, stopping, or gave up restarting the server. + Stopped, + /// Too many requests are waiting for an answer. + TooManyRequests { + /// The cap that was reached. + limit: usize, + }, + /// The document is not open in the client. + NotOpen { + /// The document's URI. + uri: String, + }, + /// The document is already open in the client. + AlreadyOpen { + /// The document's URI. + uri: String, + }, + /// The path cannot be expressed as a `file:` URI (it is relative). + InvalidPath { + /// The rejected path. + path: String, + }, + /// An edit does not fit the client's copy of the document. + Text(TextError), + /// The client's state was poisoned by a panic on another thread. + Internal { + /// What failed. + detail: String, + }, +} + +impl fmt::Display for LspError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::Spawn { command, detail } => { + write!(f, "could not start language server `{command}`: {detail}") + } + Self::Response { code, message, .. } => { + write!(f, "language server error {code}: {message}") + } + Self::Timeout { method } => { + write!(f, "language server did not answer `{method}` in time") + } + Self::Cancelled => write!(f, "request cancelled"), + Self::ServerCrashed => write!(f, "language server exited during the request"), + Self::Stopped => write!(f, "language server is stopped"), + Self::TooManyRequests { limit } => { + write!(f, "more than {limit} language server requests are pending") + } + Self::NotOpen { uri } => write!(f, "document {uri} is not open"), + Self::AlreadyOpen { uri } => write!(f, "document {uri} is already open"), + Self::InvalidPath { path } => write!(f, "path {path} is not absolute"), + Self::Text(error) => write!(f, "edit does not fit the document: {error}"), + Self::Internal { detail } => write!(f, "internal language client error: {detail}"), + } + } +} + +impl std::error::Error for LspError {} + +impl From for LspError { + fn from(error: TextError) -> Self { + Self::Text(error) + } +} diff --git a/crates/lsp/src/jsonrpc.rs b/crates/lsp/src/jsonrpc.rs new file mode 100644 index 0000000..1d86c79 --- /dev/null +++ b/crates/lsp/src/jsonrpc.rs @@ -0,0 +1,437 @@ +//! JSON-RPC 2.0 messages and the `Content-Length` framing of the LSP base +//! protocol. +//! +//! Spec: . +//! A frame is a header block (`Name: value` lines ended by `\r\n`, then an +//! empty line) followed by `Content-Length` bytes of UTF-8 JSON. Everything +//! read here comes from another process and is untrusted: header lines and +//! header counts are capped, bodies over [`MAX_MESSAGE_BYTES`] are skipped +//! without being buffered, and a malformed frame yields [`Frame::Dropped`] +//! instead of an error so the reader can carry on with the next one. + +use std::io::{self, BufRead, Read, Write}; + +use serde_json::{Map, Value, json}; + +/// The largest message body the client accepts (32 MiB). +pub const MAX_MESSAGE_BYTES: usize = 32 * 1024 * 1024; + +/// The longest header line kept; longer lines are discarded and make the +/// frame malformed. +const MAX_HEADER_LINE: usize = 1024; + +/// The most header lines one frame may have. +const MAX_HEADERS: usize = 16; + +/// The longest error message kept from a server's error response. +const MAX_ERROR_MESSAGE: usize = 4096; + +/// JSON-RPC: the method does not exist or is not supported. +pub const METHOD_NOT_FOUND: i64 = -32601; +/// JSON-RPC: invalid method parameters. +pub const INVALID_PARAMS: i64 = -32602; +/// JSON-RPC: internal error. +pub const INTERNAL_ERROR: i64 = -32603; +/// LSP: the request was cancelled by the client. +pub const REQUEST_CANCELLED: i64 = -32800; + +/// One result of [`read_frame`]. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Frame { + /// A complete message body (not yet parsed as JSON). + Body(Vec), + /// A frame that was skipped, with the reason for the log. + Dropped(String), +} + +/// Reads the next frame from `reader`. +/// +/// Blank lines before a header block are skipped. Unknown headers (such as +/// `Content-Type`) are ignored; `Content-Length` is matched case-insensitively. +/// +/// # Returns +/// `Ok(None)` at the end of the stream (also when it ends inside a frame), +/// `Ok(Some(Frame::Body))` for a complete body, and `Ok(Some(Frame::Dropped))` +/// when the header block is malformed or the body exceeds `max_bytes`; an +/// oversized body is read and discarded so the next frame starts cleanly. +/// +/// # Errors +/// Only I/O errors of the underlying reader. +pub fn read_frame(reader: &mut R, max_bytes: usize) -> io::Result> { + let mut length: Option = None; + let mut problem: Option = None; + let mut headers = 0usize; + loop { + let Some((line, overlong)) = read_line_capped(reader, MAX_HEADER_LINE)? else { + return Ok(None); + }; + if line.is_empty() && !overlong { + if headers == 0 { + continue; + } + break; + } + headers += 1; + if problem.is_some() { + continue; + } + if overlong { + problem = Some("header line too long".to_string()); + continue; + } + if headers > MAX_HEADERS { + problem = Some("too many header lines".to_string()); + continue; + } + match parse_header(&line) { + Some(Header::ContentLength(value)) => length = Some(value), + Some(Header::Other) => {} + None => { + problem = Some(format!( + "malformed header line {:?}", + String::from_utf8_lossy(&line) + )); + } + } + } + if let Some(problem) = problem { + return Ok(Some(Frame::Dropped(problem))); + } + let Some(length) = length else { + return Ok(Some(Frame::Dropped( + "header block without Content-Length".to_string(), + ))); + }; + if length > max_bytes { + let skipped = io::copy(&mut reader.take(length as u64), &mut io::sink())?; + if skipped < length as u64 { + return Ok(None); + } + return Ok(Some(Frame::Dropped(format!( + "message of {length} bytes exceeds the cap of {max_bytes} bytes" + )))); + } + let mut body = Vec::new(); + let read = reader.take(length as u64).read_to_end(&mut body)?; + if read < length { + return Ok(None); + } + Ok(Some(Frame::Body(body))) +} + +/// A header the reader understands. +enum Header { + /// `Content-Length: n`. + ContentLength(usize), + /// Any other well-formed header. + Other, +} + +/// Parses one header line (without its line break). +/// +/// # Returns +/// `None` when the line has no `:`, is not UTF-8, or has a +/// `Content-Length` value that is not a decimal number. +fn parse_header(line: &[u8]) -> Option
{ + let text = std::str::from_utf8(line).ok()?; + let (name, value) = text.split_once(':')?; + if name.trim().eq_ignore_ascii_case("content-length") { + let value = value.trim(); + if value.is_empty() || !value.bytes().all(|b| b.is_ascii_digit()) { + return None; + } + return value.parse().ok().map(Header::ContentLength); + } + Some(Header::Other) +} + +/// Reads one line ended by `\n`, keeping at most `cap` bytes. +/// +/// The trailing `\n` and a `\r` before it are removed. The rest of an +/// overlong line is consumed and discarded without buffering it. +/// +/// # Returns +/// `None` at the end of the stream before any byte; otherwise the line and +/// whether it was overlong. A last line without `\n` is returned as is. +pub(crate) fn read_line_capped( + reader: &mut R, + cap: usize, +) -> io::Result, bool)>> { + let mut line = Vec::new(); + let mut overlong = false; + let mut any = false; + loop { + let available = match reader.fill_buf() { + Ok(buf) => buf, + Err(error) if error.kind() == io::ErrorKind::Interrupted => continue, + Err(error) => return Err(error), + }; + if available.is_empty() { + if !any { + return Ok(None); + } + break; + } + any = true; + let (chunk, used, done) = match available.iter().position(|&b| b == b'\n') { + Some(at) => (available.get(..at).unwrap_or_default(), at + 1, true), + None => (available, available.len(), false), + }; + let room = cap.saturating_sub(line.len()); + if chunk.len() > room { + overlong = true; + } + line.extend_from_slice(chunk.get(..chunk.len().min(room)).unwrap_or_default()); + reader.consume(used); + if done { + break; + } + } + if line.last() == Some(&b'\r') { + line.pop(); + } + Ok(Some((line, overlong))) +} + +/// Encodes `value` as one frame: the `Content-Length` header and the JSON. +pub fn encode(value: &Value) -> Vec { + let body = value.to_string(); + let mut frame = format!("Content-Length: {}\r\n\r\n", body.len()).into_bytes(); + frame.extend_from_slice(body.as_bytes()); + frame +} + +/// Writes `value` as one frame to `writer` and flushes it. +/// +/// # Errors +/// I/O errors of the writer (a closed pipe when the server exited). +pub fn write_frame(writer: &mut W, value: &Value) -> io::Result<()> { + writer.write_all(&encode(value))?; + writer.flush() +} + +/// An error object of a JSON-RPC response. +#[derive(Debug, Clone, PartialEq)] +pub struct ResponseError { + /// The error code. + pub code: i64, + /// The message, capped at 4 KiB. + pub message: String, + /// Additional data, if any. + pub data: Option, +} + +/// A parsed JSON-RPC message. +#[derive(Debug, Clone, PartialEq)] +pub enum Message { + /// A request expecting a response with the same `id`. + Request { + /// The request id: a number or a string. + id: Value, + /// The method name. + method: String, + /// The params (`null` when absent). + params: Value, + }, + /// A notification (no `id`). + Notification { + /// The method name. + method: String, + /// The params (`null` when absent). + params: Value, + }, + /// A response to an earlier request. + Response { + /// The id of the request it answers (`null` for errors about + /// unparseable requests). + id: Value, + /// The result or the error. + result: Result, + }, +} + +impl Message { + /// Parses a message body. + /// + /// The `jsonrpc` member is not required, to be lenient with servers that + /// omit it. serde_json limits nesting to 128 levels, so deep input cannot + /// overflow the stack. + /// + /// # Errors + /// A description for the log when the body is not JSON, not an object, + /// or has neither a `method` nor a `result`/`error` with an `id`. + pub fn parse(body: &[u8]) -> Result { + let value: Value = + serde_json::from_slice(body).map_err(|error| format!("invalid JSON: {error}"))?; + let Value::Object(mut object) = value else { + return Err("message is not a JSON object".to_string()); + }; + let id = object.remove("id"); + if let Some(method) = object.remove("method") { + let Value::String(method) = method else { + return Err("method is not a string".to_string()); + }; + let params = object.remove("params").unwrap_or(Value::Null); + return match id { + None => Ok(Self::Notification { method, params }), + Some(id @ (Value::Number(_) | Value::String(_))) => { + Ok(Self::Request { id, method, params }) + } + Some(_) => Err("request id is neither a number nor a string".to_string()), + }; + } + let Some(id) = id else { + return Err("message has neither a method nor an id".to_string()); + }; + if let Some(error) = object.remove("error") { + return Ok(Self::Response { + id, + result: Err(parse_error(error)), + }); + } + match object.remove("result") { + Some(result) => Ok(Self::Response { + id, + result: Ok(result), + }), + None => Err("response has neither a result nor an error".to_string()), + } + } + + /// The message as a JSON-RPC 2.0 object. + pub fn to_json(&self) -> Value { + match self { + Self::Request { id, method, params } => { + json!({"jsonrpc": "2.0", "id": id, "method": method, "params": params}) + } + Self::Notification { method, params } => { + json!({"jsonrpc": "2.0", "method": method, "params": params}) + } + Self::Response { id, result } => match result { + Ok(result) => json!({"jsonrpc": "2.0", "id": id, "result": result}), + Err(error) => { + let mut object = Map::new(); + object.insert("code".to_string(), json!(error.code)); + object.insert("message".to_string(), json!(error.message)); + if let Some(data) = &error.data { + object.insert("data".to_string(), data.clone()); + } + json!({"jsonrpc": "2.0", "id": id, "error": object}) + } + }, + } + } +} + +/// Reads a response's `error` member leniently: a missing code becomes +/// [`INTERNAL_ERROR`], a missing message an empty one. +fn parse_error(error: Value) -> ResponseError { + let code = error + .get("code") + .and_then(Value::as_i64) + .unwrap_or(INTERNAL_ERROR); + let message = error + .get("message") + .and_then(Value::as_str) + .map(|m| truncate(m, MAX_ERROR_MESSAGE)) + .unwrap_or_default(); + let data = error.get("data").cloned(); + ResponseError { + code, + message, + data, + } +} + +/// Cuts `text` to at most `max` bytes on a character boundary. +pub(crate) fn truncate(text: &str, max: usize) -> String { + if text.len() <= max { + return text.to_string(); + } + let mut end = max; + while end > 0 && !text.is_char_boundary(end) { + end -= 1; + } + text.get(..end).unwrap_or_default().to_string() +} + +#[cfg(test)] +mod tests { + use super::*; + + fn frames(input: &[u8]) -> Vec { + let mut reader = io::BufReader::new(input); + let mut out = Vec::new(); + while let Some(frame) = read_frame(&mut reader, 64).unwrap() { + out.push(frame); + } + out + } + + #[test] + fn reads_two_frames_and_ignores_other_headers() { + let input = b"Content-Length: 2\r\n\r\n{}content-length:3\r\nContent-Type: x\r\n\r\n[1]"; + assert_eq!( + frames(input), + vec![Frame::Body(b"{}".to_vec()), Frame::Body(b"[1]".to_vec())] + ); + } + + #[test] + fn drops_oversized_and_continues() { + let mut input = b"Content-Length: 100\r\n\r\n".to_vec(); + input.extend(std::iter::repeat_n(b'x', 100)); + input.extend_from_slice(b"Content-Length: 2\r\n\r\n{}"); + let out = frames(&input); + assert!(matches!(out.first(), Some(Frame::Dropped(_)))); + assert_eq!(out.get(1), Some(&Frame::Body(b"{}".to_vec()))); + } + + #[test] + fn drops_missing_length_and_bad_lines() { + let out = frames(b"X-Foo: 1\r\n\r\ngarbage\r\n\r\nContent-Length: 2\r\n\r\n{}"); + assert_eq!(out.len(), 3); + assert_eq!(out.last(), Some(&Frame::Body(b"{}".to_vec()))); + } + + #[test] + fn eof_inside_body_ends_stream() { + assert!(frames(b"Content-Length: 10\r\n\r\n{}").is_empty()); + } + + #[test] + fn parses_message_kinds() { + assert!(matches!( + Message::parse(br#"{"jsonrpc":"2.0","id":1,"method":"a"}"#), + Ok(Message::Request { .. }) + )); + assert!(matches!( + Message::parse(br#"{"method":"a","params":[1]}"#), + Ok(Message::Notification { .. }) + )); + assert!(matches!( + Message::parse(br#"{"id":"x","result":null}"#), + Ok(Message::Response { + result: Ok(Value::Null), + .. + }) + )); + let Ok(Message::Response { + result: Err(error), .. + }) = Message::parse(br#"{"id":2,"error":{"code":-32601,"message":"no"}}"#) + else { + panic!("expected an error response"); + }; + assert_eq!(error.code, METHOD_NOT_FOUND); + assert!(Message::parse(b"[]").is_err()); + assert!(Message::parse(br#"{"id":1}"#).is_err()); + assert!(Message::parse(br#"{"id":{},"method":"a"}"#).is_err()); + assert!(Message::parse(b"{").is_err()); + } + + #[test] + fn truncate_respects_char_boundaries() { + assert_eq!(truncate("aé", 2), "a"); + assert_eq!(truncate("abc", 5), "abc"); + } +} diff --git a/crates/lsp/src/lib.rs b/crates/lsp/src/lib.rs index c4814d2..ea870a6 100644 --- a/crates/lsp/src/lib.rs +++ b/crates/lsp/src/lib.rs @@ -2,3 +2,31 @@ //! //! Speaks the Language Server Protocol to external servers (Phpactor first) //! and, later, the Debug Adapter Protocol. Server messages are untrusted input. +//! +//! - [`Server`]: spawns a server over stdio, initializes it, supervises and +//! restarts it, sends requests ([`RequestHandle`] or a callback) and keeps +//! documents in sync; [`ServerEvent`]s arrive on a channel. +//! - [`jsonrpc`]: `Content-Length` framing and JSON-RPC messages. +//! - [`types`]: the LSP structures the client parses (diagnostics, +//! locations, workspace edits), read leniently and capped. +//! - [`uri`]: `file:` URIs from and to paths. + +mod capabilities; +mod documents; +mod error; +pub mod jsonrpc; +mod server; +pub mod types; +pub mod uri; + +pub use capabilities::{ServerCapabilities, SyncKind, client_capabilities}; +pub use documents::content_changes; +pub use error::LspError; +pub use server::{ + MAX_PENDING, MessageLevel, RequestHandle, RequestId, RestartPolicy, Server, ServerEvent, + ServerOptions, Status, +}; +pub use types::{ + Diagnostic, DocumentEdits, Location, PublishDiagnostics, Range, Severity, TextEdit, + WorkspaceEdit, +}; diff --git a/crates/lsp/src/server.rs b/crates/lsp/src/server.rs new file mode 100644 index 0000000..2321421 --- /dev/null +++ b/crates/lsp/src/server.rs @@ -0,0 +1,1508 @@ +//! 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::{Child, 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_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. + /// + /// # 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); + } + command.spawn().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. 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(); + let _ = child.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(); + } +} diff --git a/crates/lsp/src/types.rs b/crates/lsp/src/types.rs new file mode 100644 index 0000000..087f138 --- /dev/null +++ b/crates/lsp/src/types.rs @@ -0,0 +1,404 @@ +//! The few LSP structures the client parses itself, read leniently from +//! untrusted JSON. +//! +//! Positions use [`lutra_text::Position`] with UTF-16 columns, the encoding +//! the client negotiates. Parsers return `None` (or skip an item) for +//! malformed input instead of failing the whole message, cap item counts +//! and cap string lengths, so a hostile server cannot make the client +//! allocate without bound. Request results without a type here (completion, +//! hover, signature help) are returned to callers as raw JSON. + +use std::path::PathBuf; + +use lutra_text::Position; +use serde_json::{Value, json}; + +use crate::jsonrpc::truncate; +use crate::uri::uri_to_path; + +/// The most diagnostics kept per `publishDiagnostics`. +pub const MAX_DIAGNOSTICS: usize = 10_000; +/// The most locations kept from one definition or references result. +pub const MAX_LOCATIONS: usize = 10_000; +/// The most text edits kept from one workspace edit. +pub const MAX_EDITS: usize = 100_000; +/// The longest diagnostic message kept, in bytes. +const MAX_MESSAGE: usize = 8 * 1024; +/// The longest short string (source, code, URI) kept, in bytes. +const MAX_SHORT: usize = 4 * 1024; + +/// A range between two positions (UTF-16 columns), end exclusive. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub struct Range { + /// The first position. + pub start: Position, + /// The position after the last character. + pub end: Position, +} + +impl Range { + /// Parses `{start: {line, character}, end: {line, character}}`. + /// + /// # Returns + /// `None` when a member is missing, negative or not an integer, or the + /// end lies before the start. + pub fn from_json(value: &Value) -> Option { + let start = position_from_json(value.get("start")?)?; + let end = position_from_json(value.get("end")?)?; + (start <= end).then_some(Self { start, end }) + } + + /// The range as LSP JSON. + pub fn to_json(&self) -> Value { + json!({"start": position_to_json(self.start), "end": position_to_json(self.end)}) + } +} + +/// Parses an LSP `Position` (`{line, character}`, both unsigned integers +/// that fit an LSP `uinteger`). +pub fn position_from_json(value: &Value) -> Option { + let line = value.get("line")?.as_u64()?; + let character = value.get("character")?.as_u64()?; + let line = usize::try_from(u32::try_from(line).ok()?).ok()?; + let column = usize::try_from(u32::try_from(character).ok()?).ok()?; + Some(Position::new(line, column)) +} + +/// The position as LSP JSON (`{line, character}`). +pub fn position_to_json(position: Position) -> Value { + json!({"line": position.line, "character": position.column}) +} + +/// How severe a diagnostic is. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Severity { + /// An error. + Error, + /// A warning. + Warning, + /// Information. + Information, + /// A hint. + Hint, +} + +impl Severity { + /// Maps the LSP number (1–4). + pub fn from_number(number: u64) -> Option { + match number { + 1 => Some(Self::Error), + 2 => Some(Self::Warning), + 3 => Some(Self::Information), + 4 => Some(Self::Hint), + _ => None, + } + } +} + +/// One diagnostic of a `textDocument/publishDiagnostics` notification. +#[derive(Debug, Clone, PartialEq)] +pub struct Diagnostic { + /// Where it applies. + pub range: Range, + /// How severe it is; `None` when the server left it out (the client + /// decides, usually as an error). + pub severity: Option, + /// The message (capped at 8 KiB). + pub message: String, + /// Who produced it (`phpstan`, `phpactor`, …), if given. + pub source: Option, + /// The diagnostic code as text (numbers are formatted), if given. + pub code: Option, +} + +impl Diagnostic { + /// Parses one diagnostic; `None` without a valid range or a message. + pub fn from_json(value: &Value) -> Option { + let range = Range::from_json(value.get("range")?)?; + let message = truncate(value.get("message")?.as_str()?, MAX_MESSAGE); + let severity = value + .get("severity") + .and_then(Value::as_u64) + .and_then(Severity::from_number); + let source = value + .get("source") + .and_then(Value::as_str) + .map(|s| truncate(s, MAX_SHORT)); + let code = match value.get("code") { + Some(Value::String(code)) => Some(truncate(code, MAX_SHORT)), + Some(Value::Number(code)) => Some(code.to_string()), + _ => None, + }; + Some(Self { + range, + severity, + message, + source, + code, + }) + } +} + +/// The params of `textDocument/publishDiagnostics`. +#[derive(Debug, Clone, PartialEq)] +pub struct PublishDiagnostics { + /// The document's URI as sent (capped). + pub uri: String, + /// The document's path, when the URI is a valid `file:` URI. + pub path: Option, + /// The document version the diagnostics belong to, if the server says. + pub version: Option, + /// The diagnostics (malformed ones skipped, at most [`MAX_DIAGNOSTICS`]). + pub diagnostics: Vec, +} + +impl PublishDiagnostics { + /// Parses the params; `None` without a URI or a diagnostics array. + pub fn from_json(value: &Value) -> Option { + let uri = truncate(value.get("uri")?.as_str()?, MAX_SHORT); + let diagnostics = value + .get("diagnostics")? + .as_array()? + .iter() + .filter_map(Diagnostic::from_json) + .take(MAX_DIAGNOSTICS) + .collect(); + Some(Self { + path: uri_to_path(&uri), + version: value.get("version").and_then(Value::as_i64), + uri, + diagnostics, + }) + } +} + +/// A location in a document. +#[derive(Debug, Clone, PartialEq)] +pub struct Location { + /// The document's URI as sent (capped). + pub uri: String, + /// The document's path, when the URI is a valid `file:` URI. + pub path: Option, + /// The range: for a `LocationLink` its `targetSelectionRange`. + pub range: Range, +} + +impl Location { + /// Parses a `Location` or a `LocationLink`. + pub fn from_json(value: &Value) -> Option { + let (uri, range) = match value.get("targetUri") { + Some(target) => ( + target.as_str()?, + value + .get("targetSelectionRange") + .or_else(|| value.get("targetRange"))?, + ), + None => (value.get("uri")?.as_str()?, value.get("range")?), + }; + let uri = truncate(uri, MAX_SHORT); + Some(Self { + path: uri_to_path(&uri), + range: Range::from_json(range)?, + uri, + }) + } + + /// Parses a definition or references result: `null`, one location, or + /// an array of `Location`/`LocationLink` (malformed items skipped, at + /// most [`MAX_LOCATIONS`]). + pub fn list_from_json(value: &Value) -> Vec { + match value { + Value::Array(items) => items + .iter() + .filter_map(Self::from_json) + .take(MAX_LOCATIONS) + .collect(), + Value::Object(_) => Self::from_json(value).into_iter().collect(), + _ => Vec::new(), + } + } +} + +/// A text edit in a document. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct TextEdit { + /// The range to replace. + pub range: Range, + /// The replacement. + pub new_text: String, +} + +impl TextEdit { + /// Parses a `TextEdit` (also an `AnnotatedTextEdit`). + pub fn from_json(value: &Value) -> Option { + Some(Self { + range: Range::from_json(value.get("range")?)?, + new_text: value.get("newText")?.as_str()?.to_string(), + }) + } +} + +/// The edits of a workspace edit for one document. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct DocumentEdits { + /// The document's URI as sent (capped). + pub uri: String, + /// The document's path, when the URI is a valid `file:` URI. + pub path: Option, + /// The version the edits were computed against, if the server says. + pub version: Option, + /// The edits; all ranges refer to the document before the edit. + pub edits: Vec, +} + +/// A parsed `WorkspaceEdit`. +#[derive(Debug, Clone, PartialEq, Eq, Default)] +pub struct WorkspaceEdit { + /// The text edits per document. + pub documents: Vec, + /// Whether the edit also asked for resource operations (create, rename, + /// delete files), which the client does not support and left out. + pub has_resource_operations: bool, + /// Whether malformed edits were skipped or the edit cap was reached; a + /// caller should refuse to apply a partial edit. + pub incomplete: bool, +} + +impl WorkspaceEdit { + /// Parses `documentChanges` when present, otherwise `changes`. + /// + /// # Returns + /// `None` when the value is not an object. + pub fn from_json(value: &Value) -> Option { + value.as_object()?; + let mut edit = Self::default(); + let mut total = 0usize; + if let Some(changes) = value.get("documentChanges").and_then(Value::as_array) { + for change in changes { + if change.get("kind").is_some() { + edit.has_resource_operations = true; + continue; + } + let document = change.get("textDocument"); + let uri = document.and_then(|d| d.get("uri")).and_then(Value::as_str); + let edits = change.get("edits").and_then(Value::as_array); + let (Some(uri), Some(edits)) = (uri, edits) else { + edit.incomplete = true; + continue; + }; + let version = document + .and_then(|d| d.get("version")) + .and_then(Value::as_i64); + edit.push(uri, version, edits, &mut total); + } + } else if let Some(changes) = value.get("changes").and_then(Value::as_object) { + for (uri, edits) in changes { + let Some(edits) = edits.as_array() else { + edit.incomplete = true; + continue; + }; + edit.push(uri, None, edits, &mut total); + } + } + Some(edit) + } + + /// Adds the edits of one document, honouring [`MAX_EDITS`] over all + /// documents (`total` counts what was kept so far). + fn push(&mut self, uri: &str, version: Option, edits: &[Value], total: &mut usize) { + let mut parsed = Vec::new(); + for value in edits { + if *total >= MAX_EDITS { + self.incomplete = true; + break; + } + match TextEdit::from_json(value) { + Some(text_edit) => { + parsed.push(text_edit); + *total += 1; + } + None => self.incomplete = true, + } + } + let uri = truncate(uri, MAX_SHORT); + self.documents.push(DocumentEdits { + path: uri_to_path(&uri), + uri, + version, + edits: parsed, + }); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn range(l1: usize, c1: usize, l2: usize, c2: usize) -> Value { + json!({"start": {"line": l1, "character": c1}, "end": {"line": l2, "character": c2}}) + } + + #[test] + fn range_rejects_bad_values() { + assert!(Range::from_json(&range(0, 1, 0, 2)).is_some()); + assert!(Range::from_json(&range(1, 0, 0, 0)).is_none()); + assert!( + Range::from_json( + &json!({"start": {"line": -1, "character": 0}, "end": {"line": 0, "character": 0}}) + ) + .is_none() + ); + assert!( + Range::from_json( + &json!({"start": {"line": 5_000_000_000u64, "character": 0}, "end": {"line": 0, "character": 0}}) + ) + .is_none() + ); + assert!(Range::from_json(&json!("x")).is_none()); + } + + #[test] + fn diagnostics_skip_malformed() { + let params = json!({ + "uri": "file:///a.php", + "version": 3, + "diagnostics": [ + {"range": range(0, 0, 0, 1), "message": "m", "severity": 2, "code": 7, "source": "s"}, + {"range": range(0, 0, 0, 1)}, + {"message": "no range"} + ] + }); + let parsed = PublishDiagnostics::from_json(¶ms).unwrap(); + assert_eq!(parsed.version, Some(3)); + assert_eq!(parsed.diagnostics.len(), 1); + let first = parsed.diagnostics.first().unwrap(); + assert_eq!(first.severity, Some(Severity::Warning)); + assert_eq!(first.code.as_deref(), Some("7")); + } + + #[test] + fn locations_accept_links_and_single() { + let link = json!({"targetUri": "file:///b.php", "targetRange": range(0,0,5,0), "targetSelectionRange": range(1, 2, 1, 4)}); + let single = json!({"uri": "file:///a.php", "range": range(0, 0, 0, 1)}); + assert_eq!(Location::list_from_json(&json!([link, single, 3])).len(), 2); + assert_eq!(Location::list_from_json(&single).len(), 1); + assert!(Location::list_from_json(&Value::Null).is_empty()); + } + + #[test] + fn workspace_edit_forms() { + let edit = json!({"newText": "x", "range": range(0, 0, 0, 1)}); + let changes = + WorkspaceEdit::from_json(&json!({"changes": {"file:///a.php": [edit, {}]}})).unwrap(); + assert_eq!(changes.documents.len(), 1); + assert!(changes.incomplete); + let documents = WorkspaceEdit::from_json(&json!({"documentChanges": [ + {"textDocument": {"uri": "file:///a.php", "version": 2}, "edits": [edit]}, + {"kind": "create", "uri": "file:///c.php"} + ]})) + .unwrap(); + assert!(documents.has_resource_operations); + assert!(!documents.incomplete); + assert_eq!(documents.documents.first().unwrap().version, Some(2)); + } +} diff --git a/crates/lsp/src/uri.rs b/crates/lsp/src/uri.rs new file mode 100644 index 0000000..c5f8845 --- /dev/null +++ b/crates/lsp/src/uri.rs @@ -0,0 +1,240 @@ +//! Conversion between file paths and `file:` URIs. +//! +//! LSP addresses documents by URI (RFC 3986). Paths become +//! `file:///C:/dir/a%20b.php` on Windows and `file:///dir/a%20b.php` on Unix: +//! every byte outside the unreserved set, `/` and a drive letter's `:` is +//! percent-encoded as UTF-8. URIs from the server are untrusted and are +//! decoded leniently (any case of escapes, an encoded drive colon, a +//! `localhost` authority) but strictly enough that a bad escape or a +//! non-`file` scheme yields `None` rather than a wrong path. + +use std::path::{Path, PathBuf}; + +use crate::LspError; + +/// Converts an absolute path to a `file:` URI. +/// +/// On Windows the verbatim prefix (`\\?\`) is removed, `\` becomes `/`, and a +/// UNC path `\\server\share\x` becomes `file://server/share/x`. +/// +/// # Errors +/// [`LspError::InvalidPath`] when the path is relative or not valid UTF-8. +pub fn path_to_uri(path: &Path) -> Result { + let invalid = || LspError::InvalidPath { + path: path.display().to_string(), + }; + if !path.is_absolute() { + return Err(invalid()); + } + let text = path.to_str().ok_or_else(invalid)?; + if cfg!(windows) { + let text = text + .strip_prefix(r"\\?\UNC\") + .map(|rest| format!(r"\\{rest}")) + .unwrap_or_else(|| text.strip_prefix(r"\\?\").unwrap_or(text).to_string()); + let slashed = text.replace('\\', "/"); + if let Some(unc) = slashed.strip_prefix("//") { + let (host, rest) = unc.split_once('/').unwrap_or((unc, "")); + return Ok(format!( + "file://{}/{}", + encode(host, false), + encode(rest, false) + )); + } + return Ok(format!("file:///{}", encode(&slashed, true))); + } + Ok(format!("file://{}", encode(text, false))) +} + +/// Converts a `file:` URI to a path. +/// +/// A query or fragment is ignored. On Windows a drive letter is returned in +/// upper case, so `file:///c%3A/x` and `file:///C:/x` give the same path. +/// +/// # Returns +/// `None` for another scheme, a bad percent escape, a decoded path that is +/// not UTF-8 or contains a NUL, or (on Unix) a host other than `localhost`. +pub fn uri_to_path(uri: &str) -> Option { + let scheme = uri.get(..7)?; + if !scheme.eq_ignore_ascii_case("file://") { + return None; + } + let rest = uri.get(7..)?; + let rest = rest.split(['?', '#']).next().unwrap_or_default(); + let (host, path) = match rest.find('/') { + Some(at) => (rest.get(..at)?, rest.get(at..)?), + None => (rest, ""), + }; + let host = decode(host)?; + let path = decode(path)?; + if path.contains('\0') || host.contains(['\0', '/', '\\']) { + return None; + } + let host = if host.eq_ignore_ascii_case("localhost") { + String::new() + } else { + host + }; + if cfg!(windows) { + if !host.is_empty() { + return Some(PathBuf::from(format!( + r"\\{host}{}", + path.replace('/', "\\") + ))); + } + let trimmed = path.strip_prefix('/').unwrap_or(&path); + let mut chars = trimmed.chars(); + if let (Some(letter), Some(':')) = (chars.next(), chars.next()) + && letter.is_ascii_alphabetic() + { + let tail = chars.as_str().replace('/', "\\"); + let tail = if tail.is_empty() { + "\\".to_string() + } else { + tail + }; + return Some(PathBuf::from(format!( + "{}:{tail}", + letter.to_ascii_uppercase() + ))); + } + return None; + } + if !host.is_empty() || !path.starts_with('/') { + return None; + } + Some(PathBuf::from(path)) +} + +/// Percent-encodes `text`, keeping unreserved characters and `/`; with +/// `drive` set, a `:` right after a leading drive letter is kept too. +fn encode(text: &str, drive: bool) -> String { + let keep_colon_at = if drive + && text.len() >= 2 + && text.as_bytes().first().is_some_and(u8::is_ascii_alphabetic) + && text.as_bytes().get(1) == Some(&b':') + { + Some(1) + } else { + None + }; + let mut out = String::with_capacity(text.len()); + for (index, byte) in text.bytes().enumerate() { + let keep = byte.is_ascii_alphanumeric() + || matches!(byte, b'-' | b'.' | b'_' | b'~' | b'/') + || keep_colon_at == Some(index); + if keep { + out.push(char::from(byte)); + } else { + out.push_str(&format!("%{byte:02X}")); + } + } + out +} + +/// Decodes percent escapes; `None` for a malformed escape or bytes that are +/// not UTF-8. +fn decode(text: &str) -> Option { + let bytes = text.as_bytes(); + let mut out = Vec::with_capacity(bytes.len()); + let mut index = 0; + while let Some(&byte) = bytes.get(index) { + if byte == b'%' { + let high = hex(*bytes.get(index + 1)?)?; + let low = hex(*bytes.get(index + 2)?)?; + out.push(high * 16 + low); + index += 3; + } else { + out.push(byte); + index += 1; + } + } + String::from_utf8(out).ok() +} + +/// The value of one hex digit. +fn hex(digit: u8) -> Option { + char::from(digit) + .to_digit(16) + .and_then(|d| u8::try_from(d).ok()) +} + +#[cfg(test)] +mod tests { + use super::*; + use proptest::prelude::*; + + fn root() -> PathBuf { + if cfg!(windows) { + PathBuf::from(r"C:\") + } else { + PathBuf::from("/") + } + } + + #[test] + fn encodes_spaces_and_unicode() { + let path = root().join("my dir").join("ä#.php"); + let uri = path_to_uri(&path).unwrap(); + if cfg!(windows) { + assert_eq!(uri, "file:///C:/my%20dir/%C3%A4%23.php"); + } else { + assert_eq!(uri, "file:///my%20dir/%C3%A4%23.php"); + } + assert_eq!(uri_to_path(&uri), Some(path)); + } + + #[test] + fn rejects_relative_and_foreign() { + assert!(path_to_uri(Path::new("a/b")).is_err()); + assert_eq!(uri_to_path("http://x/y"), None); + assert_eq!(uri_to_path("file:///a%zz"), None); + assert_eq!(uri_to_path("file:///a%"), None); + assert_eq!(uri_to_path("file:///a%00"), None); + assert_eq!(uri_to_path("fi"), None); + } + + #[cfg(windows)] + #[test] + fn windows_forms() { + assert_eq!( + uri_to_path("file:///c%3A/x/y.php"), + Some(PathBuf::from(r"C:\x\y.php")) + ); + assert_eq!( + uri_to_path("FILE://localhost/C:/x"), + Some(PathBuf::from(r"C:\x")) + ); + assert_eq!( + uri_to_path("file://server/share/a"), + Some(PathBuf::from(r"\\server\share\a")) + ); + assert_eq!(path_to_uri(Path::new(r"\\?\C:\x")).unwrap(), "file:///C:/x"); + assert_eq!( + path_to_uri(Path::new(r"\\server\share\a b")).unwrap(), + "file://server/share/a%20b" + ); + } + + proptest! { + #[test] + fn round_trips(segments in proptest::collection::vec("[^/\\\\:*?\"<>|\u{0}]{1,8}", 1..5)) { + let mut path = root(); + for segment in &segments { + let segment = segment.trim_end_matches(['.', ' ']); + if segment.is_empty() || segment == ".." || segment == "." { + continue; + } + path.push(segment); + } + let uri = path_to_uri(&path).unwrap(); + prop_assert_eq!(uri_to_path(&uri), Some(path)); + } + + #[test] + fn never_panics(input in ".{0,40}") { + let _ = uri_to_path(&input); + let _ = uri_to_path(&format!("file://{input}")); + } + } +} diff --git a/crates/lsp/tests/fake_server.rs b/crates/lsp/tests/fake_server.rs new file mode 100644 index 0000000..85011b2 --- /dev/null +++ b/crates/lsp/tests/fake_server.rs @@ -0,0 +1,502 @@ +//! The client against the scripted fake server (`lutra-lsp-fake`): +//! initialize, server requests, requests, queueing, timeout, cancel, +//! document sync, diagnostics, malformed output, crash and restart, giving +//! up, shutdown. One ignored test runs against a real Phpactor. + +#![allow( + clippy::unwrap_used, + clippy::expect_used, + clippy::indexing_slicing, + clippy::panic, + clippy::unreachable +)] + +use std::path::{Path, PathBuf}; +use std::sync::mpsc::{self, Receiver}; +use std::sync::{Mutex, MutexGuard}; +use std::time::{Duration, Instant}; + +use lutra_lsp::{ + Location, LspError, MessageLevel, RestartPolicy, Server, ServerEvent, ServerOptions, Status, +}; +use lutra_text::{Edit, Position}; +use serde_json::{Value, json}; + +const FAKE: &str = env!("CARGO_BIN_EXE_lutra-lsp-fake"); +/// How long a test waits for an event. Generous: on a loaded Windows machine +/// starting a fresh executable can stall for many seconds (virus scan). +const WAIT: Duration = Duration::from_secs(60); + +/// Serializes the tests: each starts server processes, and many parallel +/// process starts make the scanner stalls above worse. +static SERIAL: Mutex<()> = Mutex::new(()); + +fn serial() -> MutexGuard<'static, ()> { + SERIAL + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) +} + +fn options() -> ServerOptions { + ServerOptions { + request_timeout: Duration::from_secs(5), + initialize_timeout: Duration::from_secs(5), + restart: RestartPolicy { + first_delay: Duration::from_millis(20), + max_delay: Duration::from_millis(100), + max_crashes: 5, + window: Duration::from_secs(120), + }, + ..ServerOptions::default() + } +} + +fn spawn(args: &[&str], root: &Path) -> (Server, Receiver) { + Server::spawn(FAKE, args, root, options()).unwrap() +} + +/// Waits for the first event matching `pred`, returning it and every +/// event seen before it. +fn wait_for( + events: &Receiver, + mut pred: impl FnMut(&ServerEvent) -> bool, +) -> (ServerEvent, Vec) { + let deadline = Instant::now() + WAIT; + let mut seen = Vec::new(); + loop { + let left = deadline.saturating_duration_since(Instant::now()); + match events.recv_timeout(left) { + Ok(event) if pred(&event) => return (event, seen), + Ok(event) => seen.push(event), + Err(_) => panic!("event not seen; got {seen:#?}"), + } + } +} + +fn wait_ready(events: &Receiver) -> Vec { + wait_for(events, |e| *e == ServerEvent::Status(Status::Ready)).1 +} + +/// Waits for diagnostics of `path` and returns (version, message). +fn wait_diagnostics(events: &Receiver, path: &Path) -> (Option, String) { + let (event, _) = wait_for( + events, + |e| matches!(e, ServerEvent::Diagnostics(d) if d.path.as_deref() == Some(path)), + ); + let ServerEvent::Diagnostics(d) = event else { + unreachable!() + }; + let message = d + .diagnostics + .first() + .map(|d| d.message.clone()) + .unwrap_or_default(); + (d.version, message) +} + +fn notification(events: &Receiver, name: &str) -> Value { + let (event, _) = wait_for( + events, + |e| matches!(e, ServerEvent::Notification { method, .. } if method == name), + ); + let ServerEvent::Notification { params, .. } = event else { + unreachable!() + }; + params +} + +fn php_file(root: &Path, name: &str) -> PathBuf { + root.join(name) +} + +#[test] +fn initializes_and_answers_server_requests() { + let _serial = serial(); + let root = tempfile::tempdir().unwrap(); + let (server, events) = spawn(&[], root.path()); + assert_eq!(server.status(), Status::Starting); + let before = wait_ready(&events); + assert!(before.contains(&ServerEvent::Status(Status::Starting))); + let caps = server.capabilities().unwrap(); + assert!(caps.supports("hoverProvider")); + assert!(!caps.supports("renameProvider")); + let params = notification(&events, "fake/serverResponses"); + let responses = params["responses"].as_array().unwrap(); + let answer = |id: Value| { + responses + .iter() + .find(|r| r["id"] == id) + .map(|r| r["answer"].clone()) + .unwrap() + }; + assert_eq!(answer(json!("c1")), json!({"result": [null, null]})); + assert_eq!(answer(json!(2)), json!({"error": -32601})); + assert_eq!(answer(json!(3)), json!({"result": null})); + server.shutdown(); +} + +#[test] +fn delivers_log_and_stderr() { + let _serial = serial(); + let root = tempfile::tempdir().unwrap(); + let (server, events) = spawn(&[], root.path()); + let mut log = false; + let mut stderr = false; + wait_for(&events, |e| { + log |= *e + == ServerEvent::LogMessage { + level: MessageLevel::Info, + message: "hello".into(), + }; + stderr |= matches!(e, ServerEvent::Stderr(line) if line.contains("fake server started")); + log && stderr + }); + server.shutdown(); +} + +#[test] +fn typed_requests_and_errors() { + let _serial = serial(); + let root = tempfile::tempdir().unwrap(); + let (server, events) = spawn(&[], root.path()); + let path = php_file(root.path(), "a.php"); + let hover = server.hover(&path, Position::new(1, 2)).unwrap(); + wait_ready(&events); + assert_eq!( + hover.wait().unwrap()["contents"]["value"], + json!("hover 1:2") + ); + let definition = server + .definition(&path, Position::new(3, 4)) + .unwrap() + .wait() + .unwrap(); + let locations = Location::list_from_json(&definition); + assert_eq!(locations.len(), 1); + assert_eq!(locations[0].path.as_deref(), Some(path.as_path())); + assert_eq!(locations[0].range.start, Position::new(3, 4)); + let error = server.request("fake/error", Value::Null).unwrap().wait(); + assert!(matches!( + error, + Err(LspError::Response { code: -32001, .. }) + )); + let unknown = server.request("fake/nothing", Value::Null).unwrap().wait(); + assert!(matches!( + unknown, + Err(LspError::Response { code: -32601, .. }) + )); + let (sender, outcome) = mpsc::channel(); + server + .request_with( + "fake/echo", + json!({"x": 1}), + Duration::from_secs(5), + Box::new(move |result| sender.send(result).unwrap()), + ) + .unwrap(); + assert_eq!( + outcome.recv_timeout(WAIT).unwrap().unwrap(), + json!({"x": 1}) + ); + server.shutdown(); +} + +#[test] +fn timeout_sends_cancel() { + let _serial = serial(); + let root = tempfile::tempdir().unwrap(); + let (server, events) = spawn(&[], root.path()); + wait_ready(&events); + let started = Instant::now(); + let handle = server + .request_timeout("fake/sleep", Value::Null, Duration::from_millis(200)) + .unwrap(); + let id = handle.id().0; + assert!(matches!( + handle.wait(), + Err(LspError::Timeout { method }) if method == "fake/sleep" + )); + assert!(started.elapsed() >= Duration::from_millis(200)); + assert_eq!(notification(&events, "fake/cancelled")["id"], json!(id)); + server.shutdown(); +} + +#[test] +fn cancel_resolves_and_notifies() { + let _serial = serial(); + let root = tempfile::tempdir().unwrap(); + let (server, events) = spawn(&[], root.path()); + wait_ready(&events); + let handle = server.request("fake/sleep", Value::Null).unwrap(); + assert!(handle.wait_timeout(Duration::from_millis(50)).is_none()); + assert!(handle.cancel()); + assert_eq!(handle.wait(), Err(LspError::Cancelled)); + assert_eq!( + notification(&events, "fake/cancelled")["id"], + json!(handle.id().0) + ); + assert!(!handle.cancel()); + server.shutdown(); +} + +#[test] +fn incremental_sync_matches_client_copy() { + let _serial = serial(); + let root = tempfile::tempdir().unwrap(); + let (server, events) = spawn(&[], root.path()); + let path = php_file(root.path(), "a.php"); + assert_eq!( + server.did_open(&path, "php", "= 3); + assert_eq!(server.status(), Status::Ready); + server.shutdown(); +} + +#[test] +fn crash_restarts_and_reopens_documents() { + let _serial = serial(); + let root = tempfile::tempdir().unwrap(); + let mut slow = options(); + slow.restart.first_delay = Duration::from_millis(300); + slow.restart.max_delay = Duration::from_secs(1); + let (server, events) = Server::spawn(FAKE, Vec::::new(), root.path(), slow).unwrap(); + let path = php_file(root.path(), "c.php"); + server.did_open(&path, "php", "one").unwrap(); + wait_ready(&events); + wait_diagnostics(&events, &path); + server + .did_change(&path, &[Edit::replace(0..3, "two")]) + .unwrap(); + wait_diagnostics(&events, &path); + let sleeper = server.request("fake/sleep", Value::Null).unwrap(); + let crash = server.request("fake/crash", Value::Null).unwrap(); + assert_eq!(crash.wait(), Err(LspError::ServerCrashed)); + assert_eq!(sleeper.wait(), Err(LspError::ServerCrashed)); + let (event, _) = wait_for(&events, |e| { + matches!(e, ServerEvent::Status(Status::Restarting { .. })) + }); + let ServerEvent::Status(Status::Restarting { crashes, delay, .. }) = event else { + unreachable!() + }; + assert_eq!(crashes, 1); + assert_eq!(delay, Duration::from_millis(300)); + server.did_change(&path, &[Edit::insert(3, "!")]).unwrap(); + wait_ready(&events); + assert_eq!( + wait_diagnostics(&events, &path), + (Some(3), "two!".to_string()) + ); + let echo = server.request("fake/echo", json!(5)).unwrap().wait(); + assert_eq!(echo.unwrap(), json!(5)); + server.shutdown(); +} + +#[test] +fn initialize_error_counts_as_crash() { + let _serial = serial(); + let root = tempfile::tempdir().unwrap(); + let (server, events) = spawn(&["--init-error"], root.path()); + let (event, _) = wait_for(&events, |e| { + matches!(e, ServerEvent::Status(Status::Restarting { .. })) + }); + let ServerEvent::Status(Status::Restarting { reason, .. }) = event else { + unreachable!() + }; + assert!(reason.contains("initialize failed"), "{reason}"); + server.shutdown(); +} + +#[test] +fn gives_up_after_too_many_crashes() { + let _serial = serial(); + let root = tempfile::tempdir().unwrap(); + let (server, events) = spawn(&["--exit-immediately"], root.path()); + let queued = server.request("fake/echo", Value::Null).unwrap(); + let (event, seen) = wait_for(&events, |e| { + matches!(e, ServerEvent::Status(Status::Failed { .. })) + }); + assert!(matches!(event, ServerEvent::Status(Status::Failed { .. }))); + let delays: Vec = seen + .iter() + .filter_map(|e| match e { + ServerEvent::Status(Status::Restarting { delay, .. }) => Some(*delay), + _ => None, + }) + .collect(); + assert_eq!( + delays, + [20, 40, 80, 100].map(Duration::from_millis).to_vec() + ); + assert_eq!(queued.wait(), Err(LspError::Stopped)); + assert!(matches!( + server.request("fake/echo", Value::Null), + Err(LspError::Stopped) + )); + assert!(matches!(server.status(), Status::Failed { .. })); + server.shutdown(); +} + +#[test] +fn shutdown_stops_and_fails_pending() { + let _serial = serial(); + let root = tempfile::tempdir().unwrap(); + let (server, events) = spawn(&[], root.path()); + wait_ready(&events); + let sleeper = server.request("fake/sleep", Value::Null).unwrap(); + let started = Instant::now(); + server.shutdown(); + assert!(started.elapsed() < Duration::from_secs(4)); + assert_eq!(sleeper.wait(), Err(LspError::Stopped)); + wait_for(&events, |e| *e == ServerEvent::Status(Status::Stopped)); +} + +#[test] +fn spawn_errors() { + let _serial = serial(); + let root = tempfile::tempdir().unwrap(); + let missing = Server::spawn( + root.path().join("no-such-server"), + Vec::::new(), + root.path(), + options(), + ); + assert!(matches!(missing, Err(LspError::Spawn { .. }))); + let relative = Server::spawn(FAKE, Vec::::new(), Path::new("rel"), options()); + assert!(matches!(relative, Err(LspError::InvalidPath { .. }))); +} + +/// Runs against a real Phpactor: `LUTRA_PHPACTOR` is the path to +/// `phpactor.phar` (or an executable `phpactor`), `LUTRA_PHP` the PHP +/// executable (default `php`). +#[test] +#[ignore = "needs a Phpactor install (LUTRA_PHPACTOR)"] +fn real_phpactor() { + let _serial = serial(); + let phpactor = std::env::var("LUTRA_PHPACTOR").expect("LUTRA_PHPACTOR"); + let root = tempfile::tempdir().unwrap(); + let file = root.path().join("a.php"); + let text = + "bar();\n"; + std::fs::write(&file, text).unwrap(); + let (command, args) = if phpactor.ends_with(".phar") { + ( + std::env::var("LUTRA_PHP").unwrap_or_else(|_| "php".into()), + vec![phpactor.clone(), "language-server".into()], + ) + } else { + (phpactor.clone(), vec!["language-server".into()]) + }; + let started = Instant::now(); + let (server, events) = Server::spawn( + command, + args, + root.path(), + ServerOptions { + initialize_timeout: Duration::from_secs(30), + ..ServerOptions::default() + }, + ) + .unwrap(); + server.did_open(&file, "php", text).unwrap(); + wait_ready(&events); + println!("phpactor ready after {:?}", started.elapsed()); + let started = Instant::now(); + let definition = server + .definition(&file, Position::new(2, 14)) + .unwrap() + .wait() + .unwrap(); + println!("definition after {:?}: {definition}", started.elapsed()); + assert!(!Location::list_from_json(&definition).is_empty()); + let started = Instant::now(); + let hover = server.hover(&file, Position::new(2, 14)).unwrap().wait(); + println!("hover after {:?}: {hover:?}", started.elapsed()); + server.shutdown(); +} diff --git a/crates/lsp/tests/framing.rs b/crates/lsp/tests/framing.rs new file mode 100644 index 0000000..8c03418 --- /dev/null +++ b/crates/lsp/tests/framing.rs @@ -0,0 +1,139 @@ +//! Framing round trips and fuzzing of the frame reader and message parser. + +#![allow( + clippy::unwrap_used, + clippy::expect_used, + clippy::indexing_slicing, + clippy::panic +)] + +use std::io::BufReader; + +use lutra_lsp::jsonrpc::{Frame, Message, encode, read_frame}; +use proptest::prelude::*; +use serde_json::{Value, json}; + +/// Reads every frame of `input` with a cap of `max` bytes. +fn frames(input: &[u8], max: usize) -> Vec { + let mut reader = BufReader::with_capacity(7, input); + let mut out = Vec::new(); + while let Some(frame) = read_frame(&mut reader, max).unwrap() { + out.push(frame); + assert!(out.len() <= input.len() + 1, "reader does not advance"); + } + out +} + +fn json_value() -> impl Strategy { + let leaf = prop_oneof![ + Just(Value::Null), + any::().prop_map(Value::Bool), + any::().prop_map(|n| json!(n)), + ".{0,12}".prop_map(Value::String), + ]; + leaf.prop_recursive(3, 24, 4, |inner| { + prop_oneof![ + proptest::collection::vec(inner.clone(), 0..4).prop_map(Value::Array), + proptest::collection::btree_map("[a-z]{1,4}", inner, 0..4) + .prop_map(|m| Value::Object(m.into_iter().collect())), + ] + }) +} + +fn message() -> impl Strategy { + prop_oneof![ + (any::(), "[a-z/$]{1,12}", json_value()).prop_map(|(id, method, params)| { + Message::Request { + id: json!(id), + method, + params, + } + }), + ("[a-z/$]{1,12}", json_value()) + .prop_map(|(method, params)| Message::Notification { method, params }), + (any::(), json_value()).prop_map(|(id, result)| Message::Response { + id: json!(id), + result: Ok(result), + }), + ] +} + +proptest! { + #[test] + fn messages_round_trip(messages in proptest::collection::vec(message(), 0..6)) { + let mut stream = Vec::new(); + for message in &messages { + stream.extend(encode(&message.to_json())); + } + let read: Vec = frames(&stream, 1 << 20) + .into_iter() + .map(|frame| match frame { + Frame::Body(body) => Message::parse(&body).unwrap(), + Frame::Dropped(reason) => panic!("dropped: {reason}"), + }) + .collect(); + prop_assert_eq!(read, messages); + } + + #[test] + fn random_bytes_never_panic(input in proptest::collection::vec(any::(), 0..512)) { + for frame in frames(&input, 64) { + if let Frame::Body(body) = frame { + prop_assert!(body.len() <= 64); + let _ = Message::parse(&body); + } + } + } + + #[test] + fn header_like_noise_never_panics( + parts in proptest::collection::vec( + prop_oneof![ + Just(b"Content-Length: ".to_vec()), + Just(b"\r\n".to_vec()), + Just(b"\n".to_vec()), + Just(b":".to_vec()), + "[0-9]{1,3}".prop_map(String::into_bytes), + "[ -~]{0,5}".prop_map(String::into_bytes), + ], + 0..40, + ) + ) { + let input: Vec = parts.concat(); + let _ = frames(&input, 32); + } + + #[test] + fn random_json_bodies_never_panic(value in json_value()) { + let _ = Message::parse(value.to_string().as_bytes()); + } + + #[test] + fn recovers_after_bad_frames(bad in prop_oneof![ + Just(b"Content-Length: 99999\r\n\r\n".to_vec()), + Just(b"no colon\r\n\r\n".to_vec()), + Just(b"X: y\r\n\r\n".to_vec()), + Just(b"Content-Length: -1\r\n\r\n".to_vec()), + ]) { + let good = encode(&json!({"jsonrpc": "2.0", "method": "ok"})); + let mut input = bad.clone(); + if bad.starts_with(b"Content-Length: 99999") { + input.extend(std::iter::repeat_n(b' ', 99_999)); + } + input.extend(&good); + let out = frames(&input, 1024); + prop_assert!(matches!(out.first(), Some(Frame::Dropped(_)))); + prop_assert!(matches!(out.last(), Some(Frame::Body(_)))); + } +} + +#[test] +fn overlong_header_line_is_dropped_without_buffering() { + let mut input = b"Content-Length: 2".to_vec(); + input.extend(std::iter::repeat_n(b'x', 100_000)); + input.extend(b"\r\n\r\n"); + input.extend(encode(&json!({"method": "ok"}))); + let out = frames(&input, 1024); + assert!(matches!(out.first(), Some(Frame::Dropped(_)))); + assert!(matches!(out.last(), Some(Frame::Body(_)))); +} diff --git a/docs/architecture.md b/docs/architecture.md index 42bfd1d..d6d9d1e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,6 +1,6 @@ # Architecture -> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup · **Last updated:** 2026-10-17 +> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 LSP client library · **Last updated:** 2026-10-18 ## Overview @@ -273,6 +273,20 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat - Opening: Enter or a click closes the popup (focus goes back) and runs `editor.reveal` with `{path}` for files (the file's cursor stays) or `{path, line, column}` for symbols. The popup is an exclusive modal (`ModalId` `goto` in `commands/modals.ts`). Like the palette it is a launcher: running any command other than the three open commands closes it (`commands/store.ts` › `execute`), so an agent's `editor.reveal` never leaves it open. - Live check (debug build, bundled UI, port 7826, temp project with 34 files and a `vendor/` folder): `goto.fileOpen {query: "user"}` listed the two project files before the vendor one with its `library` label; `goto.classOpen {query: "usr"}` and `goto.symbolOpen {query: "User::find"}` switched the tab with marks shown; `palette.open` then `goto.fileOpen` left only the popup; an `editor.reveal` of the symbol item closed the popup and put the cursor on `find`. `goto.file` answered in < 1 ms over the control channel. Enter and clicks cannot be sent over the control channel; Vitest covers them. +### LSP client (M3.2) + +- `crates/lsp` (L3, depends on `lutra-text` and `serde_json` only) is a library; the engine wiring is M3.3. `Server::spawn(command, args, root, ServerOptions)` starts the process in `root` with piped stdio (on Windows with `CREATE_NO_WINDOW`) and returns at once with the server and a bounded `Receiver` (capacity 4096; overflow drops and counts, `dropped_events()`). A spawn error (missing executable, relative root) is returned synchronously. +- Threads, no async runtime: per process a writer (the only one touching stdin, fed by a channel), a reader (frames from stdout), a stderr drain; per server a supervisor that watches the process, expires timeouts every 20 ms, restarts and shuts down. A server is a few blocking pipes and the engine pump is synchronous, so threads with channels are simpler than pulling an executor into L3. All writes happen under the client's one mutex, so messages leave in the order the state changed; callbacks always run outside it (a panicking callback is caught). +- Framing (`jsonrpc`): `Content-Length` headers (case-insensitive, other headers ignored, header lines capped at 1 KiB and 16 per frame), bodies capped at 32 MiB (`MAX_MESSAGE_BYTES`; an oversized body is read and discarded without buffering). A malformed header block, invalid JSON or a message that is neither request, response nor notification becomes `ServerEvent::ProtocolError(reason)` (the log line) and the reader carries on with the next frame. serde_json's recursion limit bounds nesting. Proptests: message round trips, random bytes, header-like noise, recovery after bad frames, random JSON bodies. +- Initialize: `initialize` (processId, clientInfo, rootUri/rootPath, one workspace folder, `initializationOptions` from the options) with the capabilities of `client_capabilities()`: incremental sync with `didSave`, completion (no snippets, markdown/plain documentation, context), hover, signatureHelp, definition (links), references, rename with prepare, `publishDiagnostics` with versions, `workspace/configuration`, workspace folders, work-done progress, `positionEncodings: ["utf-16"]`; no dynamic registration and no `applyEdit`. Then `initialized`, every open document is (re)opened, queued requests are sent, and the status becomes `Ready`. A server choosing another encoding is logged. `initialize` times out after 30 s; a failed or late `initialize` counts as a crash. +- Requests: `request`/`request_timeout` return a `RequestHandle` (`wait`, `wait_timeout`, `try_result`, `cancel`); `request_with` takes a callback instead. Typed helpers: `completion(path, position, trigger)`, `hover`, `signature_help`, `definition`, `references(..., include_declaration)`, `prepare_rename`, `rename(..., new_name)`; results are raw JSON, with parsers in `types` for `Location::list_from_json`, `WorkspaceEdit::from_json` (documentChanges or changes; resource operations flagged, malformed edits mark it `incomplete`) and `PublishDiagnostics`. Requests issued before `Ready` are queued (the timeout runs from the call). Every request resolves exactly once: result, `Response` error, `Timeout` (default 10 s; `$/cancelRequest` is sent), `Cancelled` (also sends `$/cancelRequest`), `ServerCrashed`, or `Stopped`. At most 1024 requests are pending. +- Server requests: `workspace/configuration` gets one `null` per item (at most 1000); `window/workDoneProgress/create` and capability (un)registration are acknowledged with `null`; `window/showMessageRequest` is shown as a `ShowMessage` event and answered `null`; `workspace/workspaceFolders` returns the root; everything else gets `MethodNotFound`. Notifications become `Diagnostics`, `LogMessage`, `ShowMessage`, `Progress` or the generic `Notification`; stderr lines become `Stderr` (4 KiB cap). +- Supervision: a process exit, a failed `initialize` or a broken watch is a crash. Requests sent to that process fail with `ServerCrashed`, queued ones wait. The status goes to `Restarting {crashes, delay, reason}` with delays 1 s, 2 s, 4 s ... capped at 30 s (doubling per crash in the window); the fifth crash within 2 min ends in `Failed {message}` and fails everything with `Stopped`. All of it is `RestartPolicy` in the options (the tests use milliseconds). After a restart every open document is reopened with its current text and version. +- Document sync: the client keeps each open document in a `lutra_text::Buffer`. `did_open(path, language_id, text)` (version 1), `did_change(path, &[Edit])` with byte-range edits as in `Buffer::apply`, `did_change_full(path, text)`, `did_save(path)` (with the text if the server asks), `did_close(path)`; each change bumps the version and returns it. Edits become UTF-16 content changes (`content_changes`): touching edits are merged and the changes are sent from the end of the text to the start, so sequential application on the server equals the atomic batch, also across CRLF and surrogate pairs (property-tested). The server's `textDocumentSync` decides incremental, full or no `didChange`. Edits that do not fit the client's copy fail with `LspError::Text` and leave it unchanged. Document operations never fail because of the server's state: before `Ready` or while restarting they only update the copy. +- Shutdown: `shutdown(self)` sends `shutdown` (waits up to 2 s), `exit`, kills after 1 s, fails what is pending with `Stopped` and reports `Stopped`; it blocks for up to about 3 s, so callers run it off the engine lock. Dropping the `Server` requests the same stop in the background. +- URIs (`uri`): `path_to_uri` percent-encodes everything except unreserved characters, `/` and a drive colon (`file:///C:/a%20b.php`, UNC as `file://host/share`); `uri_to_path` accepts escapes in any case, an encoded drive colon and `localhost`, and upper-cases the drive letter; bad escapes, NUL and other schemes give `None`. +- Tests: the fake server `src/bin/lutra-lsp-fake.rs` (a test fixture, started via `CARGO_BIN_EXE_lutra-lsp-fake`) covers initialize, server requests, log and stderr, typed requests and errors, queueing before ready, timeout and cancel with `$/cancelRequest`, incremental and full sync (the fake applies the changes and publishes the text as a diagnostic), malformed output, crash, restart and reopen, initialize errors, giving up with the backoff sequence, shutdown and spawn errors (13 tests, about 0.5 s). `real_phpactor` is ignored and runs with `LUTRA_PHPACTOR` (path to `phpactor.phar`, `LUTRA_PHP` for PHP); it was not run in M3.2 (no Phpactor on the dev machine yet; M3.1 downloads it). + ## Decisions (M0) | Question | Decision | Why | @@ -290,6 +304,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat | Date | Change | Summary | |---|---|---| +| 2026-10-18 | minor | M3.2: LSP client library (`crates/lsp`: framing, supervision and restart, initialize, requests with timeout and cancel, server requests, document sync, fake server tests) | | 2026-10-17 | minor | M2.6: go-to popup (store, debounce and stale drop, modes, `editor.reveal`), `library` on `goto.file` items | | 2026-10-17 | minor | M2.7: per-buffer syntax tree off the engine lock, `syntax.outline`, `outlineChanged`, left stripe, Structure tool window | | 2026-10-17 | minor | M2.5: symbol index (`crates/index`: parallel build, updater, fuzzy queries), `index.status`, `goto.file`/`goto.class`/`goto.symbol`, `indexProgress`/`indexReady` via the pump, timing | diff --git a/docs/gaps.md b/docs/gaps.md index 10fc3c6..48f491e 100644 --- a/docs/gaps.md +++ b/docs/gaps.md @@ -1,6 +1,6 @@ # Gaps -> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app, recovery journal); G3 M1 part done (project tree, palette, settings dialog, themes); G4 under way (tree-sitter outline and folding library, Lezer highlighting, Structure tool window); G5 under way (search backend, Find tool window, symbol index, go-to popup); G14 English UI catalog in place · **Last updated:** 2026-10-17 +> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app, recovery journal); G3 M1 part done (project tree, palette, settings dialog, themes); G4 under way (tree-sitter outline and folding library, Lezer highlighting, Structure tool window); G5 under way (search backend, Find tool window, symbol index, go-to popup); G6 under way (LSP client library); G14 English UI catalog in place · **Last updated:** 2026-10-18 Every known shortfall, ranked. This is the work list: unless the owner gives a task, take the highest open gap. Hours are agent wall-clock hours for one agent, all estimated. @@ -39,10 +39,13 @@ Known smaller items from M0: - `ui.screenshot` captures the screen region of the window, so covering windows appear in the image; a webview-native capture would avoid that. - `cargo xtask fixtures` needs Composer, which the M0 machine does not have. +G6 progress: M3.2 landed the LSP client library in `crates/lsp`: JSON-RPC framing over stdio (32 MiB cap, malformed messages dropped and logged, fuzzed), `initialize` with UTF-16 positions, typed requests with timeouts and `$/cancelRequest`, answers to server requests, supervision with backoff restarts (give up after 5 crashes in 2 min) and reopening of documents, incremental document sync from `lutra_text` edits, all tested against a fake server. Not yet wired into the engine (M3.3) and not yet run against a real Phpactor; diagnostics, completion, hover, navigation and rename are still open (M3.3 to M3.5). + ## Revision history | Date | Change | Summary | |---|---|---| +| 2026-10-18 | minor | G6: LSP client library (M3.2) | | 2026-10-17 | minor | G5: go-to popup (M2.6) | | 2026-10-17 | minor | G4: Structure tool window (M2.7); G12: raw-JSON command results | | 2026-10-17 | minor | G5: symbol index and go-to commands (M2.5) |