Lutra/crates/lsp/src/jsonrpc.rs
danny 81831c90e0 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>
2026-10-18 00:57:10 +02:00

437 lines
15 KiB
Rust

//! 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");
}
}