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>
437 lines
15 KiB
Rust
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");
|
|
}
|
|
}
|