[−][src]Crate easy_jsonrpc
Easy jsonrpc
Generates rpc handlers based on a trait definition.
Defining an api
use easy_jsonrpc; #[easy_jsonrpc::rpc] pub trait Adder { fn checked_add(&self, a: isize, b: isize) -> Option<isize>; fn wrapping_add(&self, a: isize, b: isize) -> isize; fn is_some(&self, a: Option<usize>) -> bool { a.is_some() } fn takes_ref(&self, rf: &isize); }
The rpc macro generates
- An implementaion of the Handler trait for &dyn Adder
- A helper module for rpc clients
Server side usage
use easy_jsonrpc::{Handler, MaybeReply}; use serde_json::json; struct AdderImpl; impl Adder for AdderImpl { fn checked_add(&self, a: isize, b: isize) -> Option<isize> { a.checked_add(b) } fn wrapping_add(&self, a: isize, b: isize) -> isize { a.wrapping_add(b) } fn takes_ref(&self, rf: &isize) {} } let handler = (&AdderImpl {} as &dyn Adder); assert_eq!( handler.handle_request(json!({ "jsonrpc": "2.0", "method": "wrapping_add", "params": [1, 2], "id": 1 })), MaybeReply::Reply(json!({ "jsonrpc": "2.0", "result": 3, "id": 1 })) );
Client side usage
let bind = adder::checked_add(1, 2).unwrap(); let (call, tracker) = bind.call(); let json_response = match handler.handle_request(call.as_request()) { MaybeReply::Reply(resp) => resp, MaybeReply::DontReply => panic!(), }; let mut response = easy_jsonrpc::Response::from_json_response(json_response).unwrap(); assert_eq!(tracker.get_return(&mut response).unwrap(), Some(3));
Bonus bits
// Named arguments are handled for free assert_eq!( handler.handle_request(json!({ "jsonrpc": "2.0", "method": "wrapping_add", "params": { "a": 1, "b": 2 }, "id": 1 })), MaybeReply::Reply(json!({ "jsonrpc": "2.0", "result": 3, "id": 1 })) ); // Notifications (calls without an id) are handled sanely assert_eq!( handler.handle_request(json!({ "jsonrpc": "2.0", "method": "wrapping_add", "params": [1, 1] })), MaybeReply::DontReply ); // Notification are easy to generate let bind = adder::checked_add(0, 0).unwrap(); let notification = bind.notification().as_request(); assert_eq!(handler.handle_request(notification), MaybeReply::DontReply); // Batch calls are possible use easy_jsonrpc::Call; let bind0 = adder::checked_add(0, 0).unwrap(); let (call0, tracker0) = bind0.call(); let bind1 = adder::checked_add(1, 0).unwrap(); let (call1, tracker1) = bind1.call(); let bind2 = adder::wrapping_add(1, 1).unwrap(); let (call2, tracker2) = bind2.call(); let bind3 = adder::wrapping_add(1, 1).unwrap(); let call3 = bind3.notification(); let json_request = Call::batch_request(&[call0, call1, call2, call3]); let json_response = match handler.handle_request(json_request) { MaybeReply::Reply(resp) => resp, MaybeReply::DontReply => panic!(), }; let mut response = easy_jsonrpc::Response::from_json_response(json_response).unwrap(); assert_eq!(tracker1.get_return(&mut response).unwrap(), Some(1)); assert_eq!(tracker0.get_return(&mut response).unwrap(), Some(0)); assert_eq!(tracker2.get_return(&mut response).unwrap(), 2);
Re-exports
pub use easy_jsonrpc_proc_macro::rpc; |
Structs
ArgSerializeError | Thrown when arguments fail to be serialized. Possible causes include, but are not limited to: |
BoundMethod | Create a binding of arguments to a method name. Can be turned into either a jsonrpc call using call, or a jsonrpc notification using notification. |
Call | A single rpc method call with arguments. May be sent to the server by itself using as_request, or as a batch, using batch_request. |
Response | Special purpose structure for holding a group of responses. Allows for response lookup by id. Does not support non-number ids. |
Tracker | Links a jsonrpc id to a return type. Trackers can be used to get a typed return value from a json response. |
Enums
InvalidResponse | Returned by from_json_response on error. |
MaybeReply | Returned by Handler::handle_request |
Params | Represetaion of jsonrpc arguments. Passing no arguments is assumed to be semantically equivalent to passing 0 positional args, or passing a map with zero entries. |
ResponseFail | Error returned when a tracker fails to retrive its response. |
Traits
Handler | Handles jsonrpc requests. |