//! JSON-RPC 2.0 messages and the `Content-Length` framing of the LSP base //! protocol. //! //! Spec: . //! A frame is a header block (`Name: value` lines ended by `\r\n`, then an //! empty line) followed by `Content-Length` bytes of UTF-8 JSON. Everything //! read here comes from another process and is untrusted: header lines and //! header counts are capped, bodies over [`MAX_MESSAGE_BYTES`] are skipped //! without being buffered, and a malformed frame yields [`Frame::Dropped`] //! instead of an error so the reader can carry on with the next one. use std::io::{self, BufRead, Read, Write}; use serde_json::{Map, Value, json}; /// The largest message body the client accepts (32 MiB). pub const MAX_MESSAGE_BYTES: usize = 32 * 1024 * 1024; /// The longest header line kept; longer lines are discarded and make the /// frame malformed. const MAX_HEADER_LINE: usize = 1024; /// The most header lines one frame may have. const MAX_HEADERS: usize = 16; /// The longest error message kept from a server's error response. const MAX_ERROR_MESSAGE: usize = 4096; /// JSON-RPC: the method does not exist or is not supported. pub const METHOD_NOT_FOUND: i64 = -32601; /// JSON-RPC: invalid method parameters. pub const INVALID_PARAMS: i64 = -32602; /// JSON-RPC: internal error. pub const INTERNAL_ERROR: i64 = -32603; /// LSP: the request was cancelled by the client. pub const REQUEST_CANCELLED: i64 = -32800; /// One result of [`read_frame`]. #[derive(Debug, Clone, PartialEq, Eq)] pub enum Frame { /// A complete message body (not yet parsed as JSON). Body(Vec), /// A frame that was skipped, with the reason for the log. Dropped(String), } /// Reads the next frame from `reader`. /// /// Blank lines before a header block are skipped. Unknown headers (such as /// `Content-Type`) are ignored; `Content-Length` is matched case-insensitively. /// /// # Returns /// `Ok(None)` at the end of the stream (also when it ends inside a frame), /// `Ok(Some(Frame::Body))` for a complete body, and `Ok(Some(Frame::Dropped))` /// when the header block is malformed or the body exceeds `max_bytes`; an /// oversized body is read and discarded so the next frame starts cleanly. /// /// # Errors /// Only I/O errors of the underlying reader. pub fn read_frame(reader: &mut R, max_bytes: usize) -> io::Result> { let mut length: Option = None; let mut problem: Option = None; let mut headers = 0usize; loop { let Some((line, overlong)) = read_line_capped(reader, MAX_HEADER_LINE)? else { return Ok(None); }; if line.is_empty() && !overlong { if headers == 0 { continue; } break; } headers += 1; if problem.is_some() { continue; } if overlong { problem = Some("header line too long".to_string()); continue; } if headers > MAX_HEADERS { problem = Some("too many header lines".to_string()); continue; } match parse_header(&line) { Some(Header::ContentLength(value)) => length = Some(value), Some(Header::Other) => {} None => { problem = Some(format!( "malformed header line {:?}", String::from_utf8_lossy(&line) )); } } } if let Some(problem) = problem { return Ok(Some(Frame::Dropped(problem))); } let Some(length) = length else { return Ok(Some(Frame::Dropped( "header block without Content-Length".to_string(), ))); }; if length > max_bytes { let skipped = io::copy(&mut reader.take(length as u64), &mut io::sink())?; if skipped < length as u64 { return Ok(None); } return Ok(Some(Frame::Dropped(format!( "message of {length} bytes exceeds the cap of {max_bytes} bytes" )))); } let mut body = Vec::new(); let read = reader.take(length as u64).read_to_end(&mut body)?; if read < length { return Ok(None); } Ok(Some(Frame::Body(body))) } /// A header the reader understands. enum Header { /// `Content-Length: n`. ContentLength(usize), /// Any other well-formed header. Other, } /// Parses one header line (without its line break). /// /// # Returns /// `None` when the line has no `:`, is not UTF-8, or has a /// `Content-Length` value that is not a decimal number. fn parse_header(line: &[u8]) -> Option
{ let text = std::str::from_utf8(line).ok()?; let (name, value) = text.split_once(':')?; if name.trim().eq_ignore_ascii_case("content-length") { let value = value.trim(); if value.is_empty() || !value.bytes().all(|b| b.is_ascii_digit()) { return None; } return value.parse().ok().map(Header::ContentLength); } Some(Header::Other) } /// Reads one line ended by `\n`, keeping at most `cap` bytes. /// /// The trailing `\n` and a `\r` before it are removed. The rest of an /// overlong line is consumed and discarded without buffering it. /// /// # Returns /// `None` at the end of the stream before any byte; otherwise the line and /// whether it was overlong. A last line without `\n` is returned as is. pub(crate) fn read_line_capped( reader: &mut R, cap: usize, ) -> io::Result, bool)>> { let mut line = Vec::new(); let mut overlong = false; let mut any = false; loop { let available = match reader.fill_buf() { Ok(buf) => buf, Err(error) if error.kind() == io::ErrorKind::Interrupted => continue, Err(error) => return Err(error), }; if available.is_empty() { if !any { return Ok(None); } break; } any = true; let (chunk, used, done) = match available.iter().position(|&b| b == b'\n') { Some(at) => (available.get(..at).unwrap_or_default(), at + 1, true), None => (available, available.len(), false), }; let room = cap.saturating_sub(line.len()); if chunk.len() > room { overlong = true; } line.extend_from_slice(chunk.get(..chunk.len().min(room)).unwrap_or_default()); reader.consume(used); if done { break; } } if line.last() == Some(&b'\r') { line.pop(); } Ok(Some((line, overlong))) } /// Encodes `value` as one frame: the `Content-Length` header and the JSON. pub fn encode(value: &Value) -> Vec { let body = value.to_string(); let mut frame = format!("Content-Length: {}\r\n\r\n", body.len()).into_bytes(); frame.extend_from_slice(body.as_bytes()); frame } /// Writes `value` as one frame to `writer` and flushes it. /// /// # Errors /// I/O errors of the writer (a closed pipe when the server exited). pub fn write_frame(writer: &mut W, value: &Value) -> io::Result<()> { writer.write_all(&encode(value))?; writer.flush() } /// An error object of a JSON-RPC response. #[derive(Debug, Clone, PartialEq)] pub struct ResponseError { /// The error code. pub code: i64, /// The message, capped at 4 KiB. pub message: String, /// Additional data, if any. pub data: Option, } /// A parsed JSON-RPC message. #[derive(Debug, Clone, PartialEq)] pub enum Message { /// A request expecting a response with the same `id`. Request { /// The request id: a number or a string. id: Value, /// The method name. method: String, /// The params (`null` when absent). params: Value, }, /// A notification (no `id`). Notification { /// The method name. method: String, /// The params (`null` when absent). params: Value, }, /// A response to an earlier request. Response { /// The id of the request it answers (`null` for errors about /// unparseable requests). id: Value, /// The result or the error. result: Result, }, } impl Message { /// Parses a message body. /// /// The `jsonrpc` member is not required, to be lenient with servers that /// omit it. serde_json limits nesting to 128 levels, so deep input cannot /// overflow the stack. /// /// # Errors /// A description for the log when the body is not JSON, not an object, /// or has neither a `method` nor a `result`/`error` with an `id`. pub fn parse(body: &[u8]) -> Result { let value: Value = serde_json::from_slice(body).map_err(|error| format!("invalid JSON: {error}"))?; let Value::Object(mut object) = value else { return Err("message is not a JSON object".to_string()); }; let id = object.remove("id"); if let Some(method) = object.remove("method") { let Value::String(method) = method else { return Err("method is not a string".to_string()); }; let params = object.remove("params").unwrap_or(Value::Null); return match id { None => Ok(Self::Notification { method, params }), Some(id @ (Value::Number(_) | Value::String(_))) => { Ok(Self::Request { id, method, params }) } Some(_) => Err("request id is neither a number nor a string".to_string()), }; } let Some(id) = id else { return Err("message has neither a method nor an id".to_string()); }; if let Some(error) = object.remove("error") { return Ok(Self::Response { id, result: Err(parse_error(error)), }); } match object.remove("result") { Some(result) => Ok(Self::Response { id, result: Ok(result), }), None => Err("response has neither a result nor an error".to_string()), } } /// The message as a JSON-RPC 2.0 object. pub fn to_json(&self) -> Value { match self { Self::Request { id, method, params } => { json!({"jsonrpc": "2.0", "id": id, "method": method, "params": params}) } Self::Notification { method, params } => { json!({"jsonrpc": "2.0", "method": method, "params": params}) } Self::Response { id, result } => match result { Ok(result) => json!({"jsonrpc": "2.0", "id": id, "result": result}), Err(error) => { let mut object = Map::new(); object.insert("code".to_string(), json!(error.code)); object.insert("message".to_string(), json!(error.message)); if let Some(data) = &error.data { object.insert("data".to_string(), data.clone()); } json!({"jsonrpc": "2.0", "id": id, "error": object}) } }, } } } /// Reads a response's `error` member leniently: a missing code becomes /// [`INTERNAL_ERROR`], a missing message an empty one. fn parse_error(error: Value) -> ResponseError { let code = error .get("code") .and_then(Value::as_i64) .unwrap_or(INTERNAL_ERROR); let message = error .get("message") .and_then(Value::as_str) .map(|m| truncate(m, MAX_ERROR_MESSAGE)) .unwrap_or_default(); let data = error.get("data").cloned(); ResponseError { code, message, data, } } /// Cuts `text` to at most `max` bytes on a character boundary. pub(crate) fn truncate(text: &str, max: usize) -> String { if text.len() <= max { return text.to_string(); } let mut end = max; while end > 0 && !text.is_char_boundary(end) { end -= 1; } text.get(..end).unwrap_or_default().to_string() } #[cfg(test)] mod tests { use super::*; fn frames(input: &[u8]) -> Vec { let mut reader = io::BufReader::new(input); let mut out = Vec::new(); while let Some(frame) = read_frame(&mut reader, 64).unwrap() { out.push(frame); } out } #[test] fn reads_two_frames_and_ignores_other_headers() { let input = b"Content-Length: 2\r\n\r\n{}content-length:3\r\nContent-Type: x\r\n\r\n[1]"; assert_eq!( frames(input), vec![Frame::Body(b"{}".to_vec()), Frame::Body(b"[1]".to_vec())] ); } #[test] fn drops_oversized_and_continues() { let mut input = b"Content-Length: 100\r\n\r\n".to_vec(); input.extend(std::iter::repeat_n(b'x', 100)); input.extend_from_slice(b"Content-Length: 2\r\n\r\n{}"); let out = frames(&input); assert!(matches!(out.first(), Some(Frame::Dropped(_)))); assert_eq!(out.get(1), Some(&Frame::Body(b"{}".to_vec()))); } #[test] fn drops_missing_length_and_bad_lines() { let out = frames(b"X-Foo: 1\r\n\r\ngarbage\r\n\r\nContent-Length: 2\r\n\r\n{}"); assert_eq!(out.len(), 3); assert_eq!(out.last(), Some(&Frame::Body(b"{}".to_vec()))); } #[test] fn eof_inside_body_ends_stream() { assert!(frames(b"Content-Length: 10\r\n\r\n{}").is_empty()); } #[test] fn parses_message_kinds() { assert!(matches!( Message::parse(br#"{"jsonrpc":"2.0","id":1,"method":"a"}"#), Ok(Message::Request { .. }) )); assert!(matches!( Message::parse(br#"{"method":"a","params":[1]}"#), Ok(Message::Notification { .. }) )); assert!(matches!( Message::parse(br#"{"id":"x","result":null}"#), Ok(Message::Response { result: Ok(Value::Null), .. }) )); let Ok(Message::Response { result: Err(error), .. }) = Message::parse(br#"{"id":2,"error":{"code":-32601,"message":"no"}}"#) else { panic!("expected an error response"); }; assert_eq!(error.code, METHOD_NOT_FOUND); assert!(Message::parse(b"[]").is_err()); assert!(Message::parse(br#"{"id":1}"#).is_err()); assert!(Message::parse(br#"{"id":{},"method":"a"}"#).is_err()); assert!(Message::parse(b"{").is_err()); } #[test] fn truncate_respects_char_boundaries() { assert_eq!(truncate("aƩ", 2), "a"); assert_eq!(truncate("abc", 5), "abc"); } }