jsonrpc_utils/
lib.rs

1//! Alternative pub/sub, server, client and macros for jsonrpc-core.
2#![cfg_attr(docsrs, feature(doc_auto_cfg))]
3
4pub extern crate jsonrpc_core;
5pub extern crate serde_json;
6
7#[cfg(feature = "axum")]
8pub mod axum_utils;
9#[cfg(feature = "server")]
10pub mod pub_sub;
11#[cfg(feature = "server")]
12pub mod stream;
13
14mod client;
15#[cfg(any(feature = "client", feature = "blocking-client"))]
16pub use client::*;
17
18#[cfg(feature = "macros")]
19/// Using a rust trait to define RPC methods.
20///
21/// # Example
22///
23/// ```rust
24/// #[rpc]
25/// #[async_trait]
26/// trait MyRpc {
27///    async fn sleep(&self, x: u64) -> Result<u64>;
28///    // Tailing optional parameters are optional.
29///    async fn value(&self, x: Option<u64>) -> Result<u64>;
30///    async fn add(&self, (x, y): (i32, i32), z: i32) -> Result<i32>;
31///    // Override rpc method name.
32///    #[rpc(name = "@ping")]
33///    fn ping(&self) -> Result<String>;
34///
35///    type S: Stream<Item = PublishMsg<u64>> + Send + 'static;
36///    #[rpc(pub_sub(notify = "subscription", unsubscribe = "unsubscribe"))]
37///    fn subscribe(&self, interval: u64) -> Result<Self::S>;
38/// }
39///
40/// #[async_trait]
41/// impl MyRpc for MyRpcImpl {...}
42///
43/// let mut rpc = MetaIoHandler::with_compatibility(jsonrpc_core::Compatibility::V2);
44/// add_my_rpc_methods(&mut rpc, RpcImpl);
45/// ```
46///
47/// # Error handling
48///
49/// The error type must implement `Into<jsonrpc_core::Error>`.
50///
51/// # OpenRPC doc generation
52///
53/// Using `#[rpc(openrpc)]` on e.g. `trait MyRpc` will generate a `my_rpc_doc`
54/// function, which will return an OpenRPC document for the RPC methods as a
55/// `serde_json::Value`.
56///
57/// All parameters and results must implement the
58/// [JsonSchema](https://docs.rs/schemars/latest/schemars/trait.JsonSchema.html)
59/// trait.
60///
61/// Pub/sub methods won't be included in the generated doc for now.
62///
63/// Full example:
64/// [openrpc.rs](https://github.com/sopium/jsonrpc-utils/blob/master/examples/openrpc.rs)
65pub use jsonrpc_utils_macros::rpc;
66
67#[cfg(feature = "macros")]
68/// Implement RPC client methods automatically.
69///
70/// # Example
71///
72/// ```rust
73/// struct MyRpcClient {
74///    // This field must have an `rpc` method:
75///    // pub async fn rpc(&self, method: &str, params: &RawValue) -> Result<Value>
76///    inner: jsonrpc_utils::HttpClient,
77/// }
78///
79/// #[rpc_client]
80/// impl MyRpcClient {
81///     async fn sleep(&self, secs: u64) -> Result<u64>;
82///     async fn value(&self) -> Result<u64>;
83///     async fn add(&self, (x, y): (i32, i32), z: i32) -> Result<i32>;
84///     // Override rpc method name.
85///     #[rpc(name = "@ping")]
86///     async fn ping(&self) -> Result<String>;
87/// }
88/// ```
89///
90/// # Blocking Client
91///
92/// ```rust
93/// struct MyRpcClient {
94///    // This field must have an `rpc` method:
95///    // pub fn rpc(&self, method: &str, params: &RawValue) -> Result<Value>
96///     inner: jsonrpc_utils::BlockingHttpClient,
97/// }
98///
99/// #[rpc_client]
100/// impl MyRpcClient {
101///     fn sleep(&self, secs: u64) -> Result<u64>;
102///     fn add(&self, (x, y): (i32, i32), z: i32) -> Result<i32>;
103///     #[rpc(name = "@ping")]
104///     fn ping(&self) -> Result<String>;
105/// }
106/// ```
107pub use jsonrpc_utils_macros::rpc_client;
jsonrpc_utils/lib.rs

jsonrpc_utils/
lib.rs
