jrpc_types/
lib.rs

1//! This crate implements the structures as defined in the [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
2//!
3//! # Requirements
4//!
5//! These requirements derived from the specification itself.
6//!
7//! - The "jsonrpc" field MUST be present in requests, responses, and notifications. Futhormore, the value of the "jsonrpc" field MUST be "2.0".
8//! - The "id" field MUST contain a String, Number, or Null value in any request or response.
9//!   - The Null value for "id" in a request object is discouraged, as it's used for responses in which the original request id is unknown.
10//!   - The Number value for "id" SHOULD NOT contain fractional parts, as many decimal fractions cannot be represented exactly as binary fraction.
11//! - The "method" field MUST contain a String in any request.
12//! - The optional "params" field MUST be either an Object (by-name) or Array (by-position) IF the "params" are present in the request or notification.
13//!
14//! # Dependencies
15//!
16//! - **serde**: used for (de)serialization
17//! - **serde_json**: used for JSON de(serialization) implementation
18//! - **thiserror**: used for error reporting
19//!
20//! # Usage
21//!
22//! ## Requests
23//!
24//! You can easily build a JSON-RPC request:
25//! ```rust
26//! use jrpc_types::JsonRpcRequest;
27//!
28//! let data = vec![10, 293, 2, 193, 2];
29//! let req = JsonRpcRequest::builder()
30//!     .method("sort")
31//!     .params(data)
32//!     .unwrap() // Serialization of parameters could fail, so you need to catch this.
33//!     .id(2)
34//!     .build();
35//! ```
36//!
37//! Deserializing a request from a string is super easy:
38//! ```rust
39//! use jrpc_types::JsonRpcRequest;
40//!
41//! let data = r#"{"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}"#;
42//! match TryInto::<JsonRpcRequest>::try_into(data) {
43//!     Ok(req) => {
44//!         // .. do something ..
45//!     }
46//!     Err(e) => {
47//!         // .. handle error ..
48//!     }
49//! }
50//! ```
51//!
52//! ## Notifications
53//!
54//! JSON-RPC Notifications are pretty much Requests, without an ID... You can build Notifications like:
55//! ```rust
56//! use jrpc_types::JsonRpcNotification;
57//!
58//! let data = vec![10, 293, 2, 193, 2];
59//! let req = JsonRpcNotification::builder()
60//!     .method("event")
61//!     .params(data)
62//!     .unwrap() // Serialization of parameters could fail, so you need to catch this.
63//!     .build();
64//! ```
65//!
66//! Deserializing a notification from a string is super easy:
67//! ```rust
68//! use jrpc_types::JsonRpcNotification;
69//!
70//! let data = r#"{"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}"#;
71//! match TryInto::<JsonRpcNotification>::try_into(data) {
72//!     Ok(req) => {
73//!         // .. do something ..
74//!     }
75//!     Err(e) => {
76//!         // .. handle error ..
77//!     }
78//! }
79//! ```
80//!
81//! ## Response
82//!
83//! A JSON-RPC response contains different fields depending on success or error.
84//! There is also a select set of (code, message) pairs for errors that are defined in the spec.
85//! The builder implementation makes it incredibly easy to build these responses.
86//!
87//! Success response (w/ optional data):
88//! ```rust
89//! use jrpc_types::JsonRpcResponse;
90//!
91//! let data = vec![10, 293, 2, 193, 2];
92//! let req = JsonRpcResponse::builder()
93//!     .success()
94//!     .result(data)
95//!     .unwrap() // Serialization of parameters could fail, so you need to catch this.
96//!     .id(2)
97//!     .build();
98//! ```
99//!
100//! Invalid request error:
101//! ```rust
102//! use jrpc_types::JsonRpcResponse;
103//!
104//! let data = vec![10, 293, 2, 193, 2];
105//! let req = JsonRpcResponse::builder()
106//!     .error()
107//!     .invalid_request()
108//!     .id(2)
109//!     .build();
110//! ```
111//!
112//! Custom Error:
113//! ```rust
114//! use jrpc_types::JsonRpcResponse;
115//!
116//! let data = vec![10, 293, 2, 193, 2];
117//! let req = JsonRpcResponse::builder()
118//!     .error()
119//!     .code(-23)
120//!     .message("bad request man...")
121//!     .id(2)
122//!     .build();
123//! ```
124//!
125//! **NOTE**: If you are processing a JsonRpcRequest and building a JsonRpcResponse, you can use &JsonRpcRequest in the id() builder function.
126//! ```rust
127//! use jrpc_types::{JsonRpcRequest, JsonRpcResponse};
128//!
129//! // Just for docs, creating this here.. assume you have this.
130//! let req = JsonRpcRequest::builder()
131//!     .id(10)
132//!     .method("subtract")
133//!     .params_str("[5,2]")
134//!     .unwrap() // Serialization of parameters could fail, so you need to catch this.
135//!     .build();
136//!
137//! // ... process stuff ...
138//!
139//! let rsp = JsonRpcResponse::builder()
140//!     .id(&req)
141//!     .success()
142//!     .result(3)
143//!     .unwrap() // Serialization of parameters could fail, so you need to catch this.
144//!     .build();
145//! ```
146
147pub mod error;
148pub mod id;
149pub mod notification;
150pub mod params;
151pub mod request;
152pub mod response;
153pub mod version;
154
155pub use error::Error as JsonRpcError;
156pub use notification::Notification as JsonRpcNotification;
157pub use request::Request as JsonRpcRequest;
158pub use response::Response as JsonRpcResponse;
jrpc_types/lib.rs

jrpc_types/
lib.rs
