M3.2: LSP client core (framing, supervision, requests, document sync)

crates/lsp is now a library: Content-Length JSON-RPC framing over stdio
(32 MiB cap, malformed frames dropped and reported, fuzzed), Server::spawn
with initialize/initialized (utf-16, incremental sync, completion, hover,
signatureHelp, definition, references, rename, publishDiagnostics),
typed requests with timeouts and $/cancelRequest, answers to server
requests (configuration nulls, MethodNotFound), events on a bounded
channel, supervision with backoff restarts that reopen documents and
give up after 5 crashes in 2 min, shutdown/exit, and incremental
document sync from lutra_text edits. Tested against a scripted fake
server binary; docs: architecture, G6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-18 00:57:10 +02:00
parent 9ccfc1bf6a
commit 81831c90e0
15 changed files with 4089 additions and 2 deletions

6
Cargo.lock generated
View file

@ -2611,6 +2611,12 @@ dependencies = [
[[package]]
name = "lutra-lsp"
version = "0.0.0"
dependencies = [
"lutra-text",
"proptest",
"serde_json",
"tempfile",
]
[[package]]
name = "lutra-mcp"

View file

@ -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

View file

@ -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<String, Buffer>,
/// Ids of `fake/sleep` requests not yet cancelled.
sleeping: Vec<Value>,
/// 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<String> = 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<Value, ResponseError>) {
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, &params),
Message::Notification { method, params } => self.notification(&method, &params),
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<Value> = 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)
}

View file

@ -0,0 +1,210 @@
//! The client capabilities Lutra announces and the parts of the server's
//! capabilities the client acts on.
//!
//! Spec: <https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#initialize>.
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<String>,
/// 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<u64>| 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)
);
}
}

175
crates/lsp/src/documents.rs Normal file
View file

@ -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<Vec<Value>, 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<Value = (String, Vec<(usize, usize, String)>)> {
"[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<Edit> = 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),
}
}
}
}

105
crates/lsp/src/error.rs Normal file
View file

@ -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<serde_json::Value>,
},
/// 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<TextError> for LspError {
fn from(error: TextError) -> Self {
Self::Text(error)
}
}

437
crates/lsp/src/jsonrpc.rs Normal file
View file

@ -0,0 +1,437 @@
//! JSON-RPC 2.0 messages and the `Content-Length` framing of the LSP base
//! protocol.
//!
//! Spec: <https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#baseProtocol>.
//! 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<u8>),
/// 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<R: BufRead>(reader: &mut R, max_bytes: usize) -> io::Result<Option<Frame>> {
let mut length: Option<usize> = None;
let mut problem: Option<String> = 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<Header> {
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<R: BufRead>(
reader: &mut R,
cap: usize,
) -> io::Result<Option<(Vec<u8>, 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<u8> {
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<W: Write>(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<Value>,
}
/// 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<Value, ResponseError>,
},
}
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<Self, String> {
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<Frame> {
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");
}
}

View file

@ -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,
};

1508
crates/lsp/src/server.rs Normal file

File diff suppressed because it is too large Load diff

404
crates/lsp/src/types.rs Normal file
View file

@ -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<Self> {
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<Position> {
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<Self> {
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<Severity>,
/// The message (capped at 8 KiB).
pub message: String,
/// Who produced it (`phpstan`, `phpactor`, …), if given.
pub source: Option<String>,
/// The diagnostic code as text (numbers are formatted), if given.
pub code: Option<String>,
}
impl Diagnostic {
/// Parses one diagnostic; `None` without a valid range or a message.
pub fn from_json(value: &Value) -> Option<Self> {
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<PathBuf>,
/// The document version the diagnostics belong to, if the server says.
pub version: Option<i64>,
/// The diagnostics (malformed ones skipped, at most [`MAX_DIAGNOSTICS`]).
pub diagnostics: Vec<Diagnostic>,
}
impl PublishDiagnostics {
/// Parses the params; `None` without a URI or a diagnostics array.
pub fn from_json(value: &Value) -> Option<Self> {
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<PathBuf>,
/// 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<Self> {
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<Self> {
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<Self> {
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<PathBuf>,
/// The version the edits were computed against, if the server says.
pub version: Option<i64>,
/// The edits; all ranges refer to the document before the edit.
pub edits: Vec<TextEdit>,
}
/// A parsed `WorkspaceEdit`.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct WorkspaceEdit {
/// The text edits per document.
pub documents: Vec<DocumentEdits>,
/// 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<Self> {
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<i64>, 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(&params).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));
}
}

240
crates/lsp/src/uri.rs Normal file
View file

@ -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<String, LspError> {
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<PathBuf> {
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<String> {
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<u8> {
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}"));
}
}
}

View file

@ -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<ServerEvent>) {
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<ServerEvent>,
mut pred: impl FnMut(&ServerEvent) -> bool,
) -> (ServerEvent, Vec<ServerEvent>) {
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<ServerEvent>) -> Vec<ServerEvent> {
wait_for(events, |e| *e == ServerEvent::Status(Status::Ready)).1
}
/// Waits for diagnostics of `path` and returns (version, message).
fn wait_diagnostics(events: &Receiver<ServerEvent>, path: &Path) -> (Option<i64>, 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<ServerEvent>, 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", "<?php\r\necho 1;\n").unwrap(),
1
);
assert!(matches!(
server.did_open(&path, "php", ""),
Err(LspError::AlreadyOpen { .. })
));
wait_ready(&events);
assert_eq!(
wait_diagnostics(&events, &path),
(Some(1), "<?php\r\necho 1;\n".to_string())
);
let version = server
.did_change(
&path,
&[
Edit::insert(0, "😀"),
Edit::replace(12..13, "2"),
Edit::insert(15, "$x = '€';\n"),
],
)
.unwrap();
assert_eq!(version, 2);
let text = server.document_text(&path).unwrap();
assert_eq!(text, "😀<?php\r\necho 2;\n$x = '€';\n");
assert_eq!(wait_diagnostics(&events, &path), (Some(2), text.clone()));
assert!(matches!(
server.did_change(&path, &[Edit::insert(1, "x")]),
Err(LspError::Text(_))
));
assert_eq!(server.document_version(&path), Some(2));
assert_eq!(server.did_change_full(&path, "<?php\n").unwrap(), 3);
assert_eq!(
wait_diagnostics(&events, &path),
(Some(3), "<?php\n".to_string())
);
server.did_save(&path).unwrap();
assert_eq!(
notification(&events, "fake/saved")["text"],
json!("<?php\n")
);
server.did_close(&path).unwrap();
let (event, _) = wait_for(&events, |e| matches!(e, ServerEvent::Diagnostics(_)));
let ServerEvent::Diagnostics(d) = event else {
unreachable!()
};
assert!(d.diagnostics.is_empty());
assert!(matches!(
server.did_close(&path),
Err(LspError::NotOpen { .. })
));
server.shutdown();
}
#[test]
fn full_sync_sends_whole_text() {
let _serial = serial();
let root = tempfile::tempdir().unwrap();
let (server, events) = spawn(&["--sync-full"], root.path());
wait_ready(&events);
let path = php_file(root.path(), "b.php");
server.did_open(&path, "php", "ab").unwrap();
wait_diagnostics(&events, &path);
server.did_change(&path, &[Edit::insert(1, "X")]).unwrap();
assert_eq!(
wait_diagnostics(&events, &path),
(Some(2), "aXb".to_string())
);
server.shutdown();
}
#[test]
fn malformed_output_is_dropped_and_logged() {
let _serial = serial();
let root = tempfile::tempdir().unwrap();
let (server, events) = spawn(&[], root.path());
wait_ready(&events);
let result = server.request("fake/garbage", Value::Null).unwrap().wait();
assert_eq!(result.unwrap(), json!("after garbage"));
let errors = || {
let mut count = 0;
while let Ok(event) = events.recv_timeout(Duration::from_millis(200)) {
if matches!(event, ServerEvent::ProtocolError(_)) {
count += 1;
}
}
count
};
assert!(errors() >= 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::<String>::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<Duration> = 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::<String>::new(),
root.path(),
options(),
);
assert!(matches!(missing, Err(LspError::Spawn { .. })));
let relative = Server::spawn(FAKE, Vec::<String>::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 =
"<?php\nclass Foo { public function bar(): int { return 1; } }\n(new Foo())->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();
}

139
crates/lsp/tests/framing.rs Normal file
View file

@ -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<Frame> {
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<Value = Value> {
let leaf = prop_oneof![
Just(Value::Null),
any::<bool>().prop_map(Value::Bool),
any::<i64>().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<Value = Message> {
prop_oneof![
(any::<i32>(), "[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::<i32>(), 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<Message> = 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::<u8>(), 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<u8> = 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(_))));
}

View file

@ -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<ServerEvent>` (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 |

View file

@ -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) |