diff --git a/Cargo.lock b/Cargo.lock index 12a8107e7..8e12a6995 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1970,6 +1970,13 @@ dependencies = [ "zune-jpeg", ] +[[package]] +name = "craft-jsonrpc" +version = "0.1.0" +dependencies = [ + "serde_json", +] + [[package]] name = "craft-jxl" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 190160671..5d0bbbc66 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -89,6 +89,7 @@ craft-indd = { path = "crates/indd" } craft-jmap = { path = "crates/jmap" } craft-ical = { path = "crates/ical" } craft-jpeg = { path = "crates/jpeg" } +craft-jsonrpc = { path = "crates/jsonrpc" } craft-jxl = { path = "crates/jxl" } craft-kiwi = { path = "crates/kiwi" } craft-keymap = { path = "crates/keymap" } diff --git a/crates/jsonrpc/Cargo.toml b/crates/jsonrpc/Cargo.toml new file mode 100644 index 000000000..7456ececf --- /dev/null +++ b/crates/jsonrpc/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "craft-jsonrpc" +description = "Bounded JSON-RPC 2.0 server envelopes without transport or application routing" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +[dependencies] +serde_json = { workspace = true } diff --git a/crates/jsonrpc/README.md b/crates/jsonrpc/README.md new file mode 100644 index 000000000..8711c25ff --- /dev/null +++ b/crates/jsonrpc/README.md @@ -0,0 +1,31 @@ +# craft-jsonrpc + +`craft-jsonrpc` provides bounded JSON-RPC 2.0 server envelopes independently of a transport or an +application's method router. It can read a bounded newline-delimited message, parse it from bytes, +check request IDs and batch sizes, dispatch requests and notifications separately, and build +response envelopes. It does not start a server, choose an MCP protocol version, or interpret tool +names and arguments. + +`Limits` defaults to 64 MiB per message and 4096 batch entries. `parse_json` checks the byte limit +before deserialization, and `process` rejects an oversized batch before calling any handler. +For newline-delimited transports, `read_line` bounds memory while reading; after an over-limit +line, the caller must close the stream or discard the rest of that line. +`serde_json`'s nesting limit remains in effect. Response sizes are the caller's responsibility. + +A valid request receives the handler's result or error with its original string, numeric, or null +ID. The default accepts numeric IDs as required by [JSON-RPC 2.0](https://www.jsonrpc.org/specification#request_object), +which discourages fractional values. Set `integer_ids_only` and clear `allow_null_ids` for +protocols such as MCP that require integer or string IDs. A legacy server can retain its previous +null-ID behavior independently. An omitted ID is a notification: it calls the separate notification +handler and gets no reply. +Malformed batch entries receive an invalid-request error; an empty batch gets one error response; +a batch containing only notifications has no response. Invalid parameter shapes receive an +invalid-params error for requests and no reply for notifications. The handler decides whether +object or array parameters are valid for each method. + +The caller may inspect the bounded parsed value before `process` to support an existing legacy +protocol. Parse failures and limit failures are returned explicitly so each transport can choose +its error and connection policy; `parse_error_response` builds the JSON-RPC parse error. + +The envelope behavior is extracted from StencilCraft's JSON-lines MCP/control server. App-specific +method routing, legacy control requests, and MCP lifecycle policy stay with the app. diff --git a/crates/jsonrpc/src/lib.rs b/crates/jsonrpc/src/lib.rs new file mode 100644 index 000000000..9f8128d1d --- /dev/null +++ b/crates/jsonrpc/src/lib.rs @@ -0,0 +1,197 @@ +//! Bounded JSON-RPC 2.0 server envelopes without a transport or application router. +//! +//! Parse a bounded line with [`parse_json`], then pass the value to [`process`]. A host may +//! inspect the parsed value first for a legacy protocol. `process` validates envelopes, dispatches +//! requests and notifications separately, and constructs single or batch replies. The host owns +//! the transport, method semantics and response-size policy. + +#![forbid(unsafe_code)] +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +use serde_json::{Value, json}; +use std::io::BufRead; + +/// Bounds on a single JSON document and on the number of requests in a batch. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Limits { + pub max_message_bytes: usize, + pub max_batch_items: usize, + /// Reject fractional JSON numbers as IDs for protocols that require integer IDs. + pub integer_ids_only: bool, + /// Permit an explicit null request ID, as JSON-RPC does; some protocols prohibit it. + pub allow_null_ids: bool, +} + +impl Default for Limits { + fn default() -> Self { + Self { max_message_bytes: 64 * 1024 * 1024, max_batch_items: 4096, integer_ids_only: false, allow_null_ids: true } + } +} + +/// Failure before dispatch. An over-limit batch is rejected before any callback is invoked. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum ParseError { + MessageTooLarge, + InvalidJson, + BatchTooLarge, +} + +impl std::fmt::Display for ParseError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(match self { + Self::MessageTooLarge => "JSON-RPC message exceeds the byte limit", + Self::InvalidJson => "invalid JSON", + Self::BatchTooLarge => "JSON-RPC batch exceeds the item limit", + }) + } +} +impl std::error::Error for ParseError {} + +/// Error reading a newline-delimited message. After `TooLong`, close or otherwise discard the +/// remaining input line before reading another message. +#[derive(Debug)] +pub enum LineError { + Io(std::io::Error), + TooLong, +} + +impl std::fmt::Display for LineError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Self::Io(error) => write!(f, "message read failed: {error}"), + Self::TooLong => f.write_str("message exceeds the byte limit"), + } + } +} +impl std::error::Error for LineError { + fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { + match self { + Self::Io(error) => Some(error), + Self::TooLong => None, + } + } +} + +/// Read at most `max_bytes` before a newline, without allocating for an oversized line. The +/// newline is consumed but omitted from the returned bytes. EOF with no bytes returns `None`; +/// an empty line returns `Some(Vec::new())`. +pub fn read_line(reader: &mut R, max_bytes: usize) -> Result>, LineError> { + let mut line = Vec::new(); + loop { + let bytes = reader.fill_buf().map_err(LineError::Io)?; + if bytes.is_empty() { + return Ok((!line.is_empty()).then_some(line)); + } + let newline = bytes.iter().position(|&byte| byte == b'\n'); + let len = newline.unwrap_or(bytes.len()); + if line.len().saturating_add(len) > max_bytes { + return Err(LineError::TooLong); + } + line.extend_from_slice(&bytes[..len]); + reader.consume(len + usize::from(newline.is_some())); + if newline.is_some() { + return Ok(Some(line)); + } + } +} + +/// Parse JSON after checking its byte length. `serde_json` also bounds nesting depth. +pub fn parse_json(bytes: &[u8], limits: Limits) -> Result { + if bytes.len() > limits.max_message_bytes { + return Err(ParseError::MessageTooLarge); + } + serde_json::from_slice(bytes).map_err(|_| ParseError::InvalidJson) +} + +/// A validated request or notification. A present null `id` is distinct from an omitted `id`. +#[derive(Clone, Copy, Debug)] +pub struct Request<'a> { + pub id: Option<&'a Value>, + pub method: &'a str, + pub params: Option<&'a Value>, +} + +/// Inspect a single request envelope. This validates its JSON-RPC version, method and ID; +/// [`process`] additionally validates parameter shape before dispatching it. +pub fn request(value: &Value, limits: Limits) -> Option> { + let object = value.as_object()?; + let id = object.get("id"); + let valid_id = id.is_none_or(|v| { + (v.is_null() && limits.allow_null_ids) || v.is_string() || if limits.integer_ids_only { v.is_i64() || v.is_u64() } else { v.is_number() } + }); + if object.get("jsonrpc").and_then(Value::as_str) != Some("2.0") || !valid_id { + return None; + } + Some(Request { id, method: object.get("method")?.as_str()?, params: object.get("params") }) +} + +/// A JSON-RPC error returned by a method handler. +#[derive(Clone, Debug, PartialEq)] +pub struct RpcError { + pub code: i64, + pub message: String, + pub data: Option, +} + +impl RpcError { + pub fn new(code: i64, message: impl Into) -> Self { + Self { code, message: message.into(), data: None } + } +} + +/// Build an error response, including optional error data. +pub fn error_response(id: Value, error: RpcError) -> Value { + let mut detail = json!({"code": error.code, "message": error.message}); + if let (Some(data), Some(object)) = (error.data, detail.as_object_mut()) { + object.insert("data".into(), data); + } + json!({"jsonrpc": "2.0", "id": id, "error": detail}) +} + +/// Build the standard parse-error response for input that is not JSON. +pub fn parse_error_response() -> Value { + error_response(Value::Null, RpcError::new(-32700, "Parse error")) +} + +fn invalid_request() -> Value { + error_response(Value::Null, RpcError::new(-32600, "Invalid Request")) +} + +fn one(value: &Value, limits: Limits, on_request: &mut F, on_notification: &mut N) -> Option +where + F: FnMut(Request<'_>) -> Result, + N: FnMut(Request<'_>), +{ + let Some(request) = request(value, limits) else { return Some(invalid_request()) }; + let id = request.id; + if request.params.is_some_and(|v| !v.is_object() && !v.is_array()) { + return id.map(|id| error_response(id.clone(), RpcError::new(-32602, "Invalid params"))); + } + let Some(id) = id else { + on_notification(request); + return None; + }; + Some(match on_request(request) { + Ok(result) => json!({"jsonrpc": "2.0", "id": id, "result": result}), + Err(error) => error_response(id.clone(), error), + }) +} + +/// Process a parsed JSON-RPC message. Notifications never receive a response. Invalid batch +/// entries produce individual errors; an empty batch produces one invalid-request response. +/// A batch over the limit returns [`ParseError::BatchTooLarge`] without invoking either callback. +pub fn process(value: &Value, limits: Limits, mut on_request: F, mut on_notification: N) -> Result, ParseError> +where + F: FnMut(Request<'_>) -> Result, + N: FnMut(Request<'_>), +{ + let Some(batch) = value.as_array() else { return Ok(one(value, limits, &mut on_request, &mut on_notification)) }; + if batch.len() > limits.max_batch_items { + return Err(ParseError::BatchTooLarge); + } + if batch.is_empty() { + return Ok(Some(invalid_request())); + } + let responses: Vec<_> = batch.iter().filter_map(|v| one(v, limits, &mut on_request, &mut on_notification)).collect(); + Ok((!responses.is_empty()).then_some(Value::Array(responses))) +} diff --git a/crates/jsonrpc/tests/server.rs b/crates/jsonrpc/tests/server.rs new file mode 100644 index 000000000..a9186f4ae --- /dev/null +++ b/crates/jsonrpc/tests/server.rs @@ -0,0 +1,172 @@ +use craft_jsonrpc::{Limits, ParseError, RpcError, parse_error_response, parse_json, process}; +use serde_json::{Value, json}; + +#[test] +fn batches_preserve_ids_order_and_suppress_notification_replies() { + let input = json!([ + {"jsonrpc": "2.0", "method": "notifications/initialized"}, + {"jsonrpc": "2.0", "id": "a", "method": "ping"}, + {"jsonrpc": "2.0", "id": 2, "method": "unknown"}, + 17, + {"jsonrpc": "2.0", "id": null, "method": "ping"} + ]); + let mut notifications = Vec::new(); + let result = process( + &input, + Limits::default(), + |request| match request.method { + "ping" => Ok(json!({})), + _ => Err(RpcError::new(-32601, "Method not found")), + }, + |request| notifications.push(request.method.to_owned()), + ) + .unwrap() + .unwrap(); + assert_eq!(notifications, ["notifications/initialized"]); + assert_eq!( + result, + json!([ + {"jsonrpc":"2.0", "id":"a", "result":{}}, + {"jsonrpc":"2.0", "id":2, "error":{"code":-32601,"message":"Method not found"}}, + {"jsonrpc":"2.0", "id":null, "error":{"code":-32600,"message":"Invalid Request"}}, + {"jsonrpc":"2.0", "id":null, "result":{}} + ]) + ); +} + +#[test] +fn notifications_never_receive_responses_including_all_notification_batches() { + let input = json!([ + {"jsonrpc":"2.0", "method":"tools/call", "params":{"name":"mutating"}}, + {"jsonrpc":"2.0", "method":"notifications/initialized"} + ]); + let mut requests = 0; + let mut notices = 0; + let result = process( + &input, + Limits::default(), + |_| { + requests += 1; + Ok(Value::Null) + }, + |_| notices += 1, + ) + .unwrap(); + assert!(result.is_none()); + assert_eq!(requests, 0); + assert_eq!(notices, 2); +} + +#[test] +fn invalid_envelopes_and_params_return_standard_errors() { + for id in [json!(true), json!([]), json!({})] { + let input = json!({"jsonrpc":"2.0", "id":id, "method":"ping"}); + let reply = process(&input, Limits::default(), |_| panic!("invalid id dispatched"), |_| panic!("invalid id notified")).unwrap().unwrap(); + assert_eq!(reply["id"], Value::Null); + assert_eq!(reply["error"]["code"], -32600); + } + for input in [json!({}), json!({"jsonrpc":"1.0", "id":1, "method":"ping"}), json!({"jsonrpc":"2.0", "id":1}), json!([])] { + let reply = + process(&input, Limits::default(), |_| panic!("invalid request dispatched"), |_| panic!("invalid notification")).unwrap().unwrap(); + assert_eq!(reply["error"]["code"], -32600); + } + let input = json!({"jsonrpc":"2.0", "id":4, "method":"ping", "params":17}); + let reply = process(&input, Limits::default(), |_| panic!("invalid params dispatched"), |_| {}).unwrap().unwrap(); + assert_eq!(reply["id"], 4); + assert_eq!(reply["error"]["code"], -32602); + let notification = json!({"jsonrpc":"2.0", "method":"notice", "params":17}); + assert!(process(¬ification, Limits::default(), |_| panic!("invalid request"), |_| panic!("invalid notification")).unwrap().is_none()); +} + +#[test] +fn arrays_are_valid_params_and_errors_can_include_data() { + let input = json!({"jsonrpc":"2.0", "id":-7, "method":"test", "params":[1, 2]}); + let reply = process( + &input, + Limits::default(), + |request| { + assert_eq!(request.params, Some(&json!([1, 2]))); + let mut error = RpcError::new(-32000, "failure"); + error.data = Some(json!({"why":"example"})); + Err(error) + }, + |_| {}, + ) + .unwrap() + .unwrap(); + assert_eq!(reply, json!({"jsonrpc":"2.0", "id":-7, "error":{"code":-32000,"message":"failure","data":{"why":"example"}}})); +} + +#[test] +fn parse_and_batch_limits_apply_before_dispatch() { + let limits = Limits { max_message_bytes: 3, max_batch_items: 1, ..Limits::default() }; + assert_eq!(parse_json(b"null", limits), Err(ParseError::MessageTooLarge)); + assert_eq!(parse_json(b"123", limits).unwrap(), json!(123)); + assert_eq!(parse_json(b"{", limits), Err(ParseError::InvalidJson)); + assert_eq!(parse_error_response()["error"]["code"], -32700); + let input = json!([{"jsonrpc":"2.0", "id":1, "method":"ping"}, {"jsonrpc":"2.0", "method":"notice"}]); + assert_eq!( + process(&input, limits, |_| panic!("over-limit batch dispatched"), |_| panic!("over-limit batch notified")), + Err(ParseError::BatchTooLarge) + ); + let one = json!([{"jsonrpc":"2.0", "id":1, "method":"ping"}]); + assert_eq!(process(&one, limits, |_| Ok(json!({})), |_| {}).unwrap().unwrap().as_array().unwrap().len(), 1); +} + +#[test] +fn invalid_utf8_and_excessive_nesting_are_rejected() { + assert_eq!(parse_json(&[0xff], Limits::default()), Err(ParseError::InvalidJson)); + let nested = format!("{}0{}", "[".repeat(200), "]".repeat(200)); + assert_eq!(parse_json(nested.as_bytes(), Limits::default()), Err(ParseError::InvalidJson)); +} + +#[test] +fn bounded_line_read_handles_chunks_empty_lines_and_eof() { + use std::io::{BufReader, Cursor}; + let mut reader = BufReader::with_capacity(2, Cursor::new(b"abc\n\nxy")); + assert_eq!(craft_jsonrpc::read_line(&mut reader, 3).unwrap(), Some(b"abc".to_vec())); + assert_eq!(craft_jsonrpc::read_line(&mut reader, 3).unwrap(), Some(Vec::new())); + assert_eq!(craft_jsonrpc::read_line(&mut reader, 3).unwrap(), Some(b"xy".to_vec())); + assert_eq!(craft_jsonrpc::read_line(&mut reader, 3).unwrap(), None); + let mut too_long = BufReader::with_capacity(2, Cursor::new(b"abcd\n")); + assert!(matches!(craft_jsonrpc::read_line(&mut too_long, 3), Err(craft_jsonrpc::LineError::TooLong))); +} + +#[test] +fn bounded_line_read_propagates_io_errors() { + struct Broken; + impl std::io::Read for Broken { + fn read(&mut self, _: &mut [u8]) -> std::io::Result { + Err(std::io::Error::other("broken")) + } + } + let mut reader = std::io::BufReader::new(Broken); + assert!(matches!(craft_jsonrpc::read_line(&mut reader, 1), Err(craft_jsonrpc::LineError::Io(_)))); +} + +#[test] +fn inspect_single_request_distinguishes_null_ids_and_invalid_envelopes() { + let request = json!({"jsonrpc":"2.0", "id":null, "method":"ping"}); + let parsed = craft_jsonrpc::request(&request, Limits::default()).unwrap(); + assert_eq!(parsed.id, Some(&Value::Null)); + assert_eq!(parsed.method, "ping"); + let notification = json!({"jsonrpc":"2.0", "method":"ping"}); + assert!(craft_jsonrpc::request(¬ification, Limits::default()).unwrap().id.is_none()); + assert!(craft_jsonrpc::request(&json!({"jsonrpc":"2.0", "id":false, "method":"ping"}), Limits::default()).is_none()); + assert!(craft_jsonrpc::request(&json!({"method":"ping"}), Limits::default()).is_none()); +} + +#[test] +fn numeric_ids_follow_the_selected_protocol_policy() { + let input = json!({"jsonrpc":"2.0", "id":1.5, "method":"ping"}); + let reply = process(&input, Limits::default(), |_| Ok(json!({})), |_| {}).unwrap().unwrap(); + assert_eq!(reply["id"], json!(1.5)); + let strict = Limits { integer_ids_only: true, ..Limits::default() }; + let reply = process(&input, strict, |_| panic!("fractional ID dispatched"), |_| {}).unwrap().unwrap(); + assert_eq!(reply["id"], Value::Null); + assert_eq!(reply["error"]["code"], -32600); + let no_null = Limits { allow_null_ids: false, ..strict }; + let null_id = json!({"jsonrpc":"2.0", "id":null, "method":"ping"}); + let reply = process(&null_id, no_null, |_| panic!("null ID dispatched"), |_| {}).unwrap().unwrap(); + assert_eq!(reply["error"]["code"], -32600); +}