mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-17 20:25:06 +00:00
260 lines
10 KiB
Rust
260 lines
10 KiB
Rust
//! 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)]
|
|
|
|
#[cfg(feature = "async-lines")]
|
|
pub mod async_lines;
|
|
pub mod control;
|
|
|
|
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)))
|
|
}
|
|
/// Process a permissive legacy JSON-RPC envelope. This mode accepts arbitrary IDs and
|
|
/// parameter shapes, ignores response envelopes, and retains legacy diagnostic messages.
|
|
/// The caller supplies dispatch and notification callbacks, and should bound transport input.
|
|
pub fn process_legacy<F, N>(value: &Value, mut on_request: F, mut on_notification: N) -> Option<Value>
|
|
where
|
|
F: FnMut(Request<'_>) -> Result<Value, RpcError>,
|
|
N: FnMut(Request<'_>),
|
|
{
|
|
fn one<F, N>(value: &Value, on_request: &mut F, on_notification: &mut N) -> Option<Value>
|
|
where
|
|
F: FnMut(Request<'_>) -> Result<Value, RpcError>,
|
|
N: FnMut(Request<'_>),
|
|
{
|
|
let Some(object) = value.as_object() else { return Some(error_response(Value::Null, RpcError::new(-32600, "message must be an object"))) };
|
|
let id = object.get("id");
|
|
let Some(method) = object.get("method").and_then(Value::as_str) else {
|
|
if object.contains_key("result") || object.contains_key("error") {
|
|
return None;
|
|
}
|
|
return Some(error_response(id.cloned().unwrap_or(Value::Null), RpcError::new(-32600, "missing `method`")));
|
|
};
|
|
let request = Request { id, method, params: object.get("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),
|
|
})
|
|
}
|
|
if let Some(batch) = value.as_array() {
|
|
if batch.is_empty() {
|
|
return Some(error_response(Value::Null, RpcError::new(-32600, "empty batch")));
|
|
}
|
|
let replies: Vec<_> = batch.iter().filter_map(|v| one(v, &mut on_request, &mut on_notification)).collect();
|
|
(!replies.is_empty()).then_some(Value::Array(replies))
|
|
} else {
|
|
one(value, &mut on_request, &mut on_notification)
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod legacy_tests {
|
|
use super::*;
|
|
#[test]
|
|
fn preserves_legacy_batch_routing_and_errors() {
|
|
let input = json!([{"id": [1], "method":"echo", "params":5}, {"method":"notice"}, {"result":1}, {}, 7]);
|
|
let seen = std::cell::Cell::new(false);
|
|
let result = process_legacy(&input, |r| Ok(r.params.cloned().unwrap_or(Value::Null)), |_| seen.set(true)).unwrap();
|
|
assert!(seen.get());
|
|
assert_eq!(
|
|
result,
|
|
json!([{"jsonrpc":"2.0","id":[1],"result":5}, {"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"missing `method`"}}, {"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"message must be an object"}}])
|
|
);
|
|
assert_eq!(process_legacy(&json!([]), |_| Ok(Value::Null), |_| {}).unwrap()["error"]["message"], "empty batch");
|
|
}
|
|
}
|