mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-16 23:42:27 +00:00
Merge pull request #1575 from storytold/codex/jsonrpc-envelope
Add bounded JSON-RPC server envelopes
This commit is contained in:
6 files changed
+422
No files matched your search
Generated
+7
@@ -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"
|
||||
|
||||
@@ -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" }
|
||||
|
||||
@@ -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 }
|
||||
@@ -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.
|
||||
@@ -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<R: BufRead>(reader: &mut R, max_bytes: usize) -> Result<Option<Vec<u8>>, 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<Value, ParseError> {
|
||||
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<Request<'_>> {
|
||||
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<Value>,
|
||||
}
|
||||
|
||||
impl RpcError {
|
||||
pub fn new(code: i64, message: impl Into<String>) -> 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<F, N>(value: &Value, limits: Limits, on_request: &mut F, on_notification: &mut N) -> Option<Value>
|
||||
where
|
||||
F: FnMut(Request<'_>) -> Result<Value, RpcError>,
|
||||
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<F, N>(value: &Value, limits: Limits, mut on_request: F, mut on_notification: N) -> Result<Option<Value>, ParseError>
|
||||
where
|
||||
F: FnMut(Request<'_>) -> Result<Value, RpcError>,
|
||||
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)))
|
||||
}
|
||||
@@ -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<usize> {
|
||||
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);
|
||||
}
|
||||
Reference in new issue
Block a user