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

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(_))));
}