[−][src]Crate jrpc
jrpc: an ultra lightweight crate for types from the jsonrpc spec
This crate defines the datatypes for the jsonrpc spec... and that is IT.
This crate never touches the network, filesystem, etc. It simply uses serde to easily construct, serialize and deserialize Request and Response data types.
Specification
The below is directly copy/pasted from: http://www.jsonrpc.org/specification
The types try to correctly copy the relevant documentation snippets in their docstring.
1 Overview
JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over http, or in many various message passing environments. It uses JSON (RFC 4627) as data format.
It is designed to be simple!
2 Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Since JSON-RPC utilizes JSON, it has the same type system (see http://www.json.org or RFC 4627). JSON can represent four primitive types (Strings, Numbers, Booleans, and Null) and two structured types (Objects and Arrays). The term "Primitive" in this specification references any of those four primitive JSON types. The term "Structured" references either of the structured JSON types. Whenever this document refers to any JSON type, the first letter is always capitalized: Object, Array, String, Number, Boolean, Null. True and False are also capitalized.
All member names exchanged between the Client and the Server that are considered for matching of any kind should be considered to be case-sensitive. The terms function, method, and procedure can be assumed to be interchangeable.
The Client is defined as the origin of Request objects and the handler of Response objects.
The Server is defined as the origin of Response objects and the handler of Request objects.
One implementation of this specification could easily fill both of those roles, even at the same time, to other different clients or the same client. This specification does not address that layer of complexity.
3 Compatibility
JSON-RPC 2.0 Request objects and Response objects may not work with existing JSON-RPC 1.0 clients or servers. However, it is easy to distinguish between the two versions as 2.0 always has a member named "jsonrpc" with a String value of "2.0" whereas 1.0 does not. Most 2.0 implementations should consider trying to handle 1.0 objects, even if not the peer-to-peer and class hinting aspects of 1.0.
4 Request Object
See Request
4.1 Notification
See IdReq
4.2 Parameter Structures
See Request.params
5 Response object
See Response
5.1 Error object
See ErrorObject
6 Batch
Note: simply use a
Vec<Request>
andVec<Response>
To send several Request objects at the same time, the Client MAY send an Array filled with Request objects.
The Server should respond with an Array containing the corresponding Response objects, after all of the batch Request objects have been processed. A Response object SHOULD exist for each Request object, except that there SHOULD NOT be any Response objects for notifications. The Server MAY process a batch rpc call as a set of concurrent tasks, processing them in any order and with any width of parallelism.
The Response objects being returned from a batch call MAY be returned in any order within the Array. The Client SHOULD match contexts between the set of Request objects and the resulting set of Response objects based on the id member within each Object.
If the batch rpc call itself fails to be recognized as an valid JSON or as an Array with at least one value, the response from the Server MUST be a single Response object. If there are no Response objects contained within the Response array as it is to be sent to the client, the server MUST NOT return an empty Array and should return nothing at all.
7 Examples
Ommitted. See the specification
8 Extensions
This library does not support checking for extensions. See
Request.method
for more details of the spec.
Structs
Error | The jsonrpc Error response, indicating an error. |
ErrorObject | The jsonrpc Error object, with details of the error. |
Request | A rpc call is represented by sending a Request object to a Server. |
Success | The jsonrpc Success response, indicating a successful result. |
V2_0 | The |
Enums
ErrorCode | A Number that indicates the error type that occurred. This MUST be an integer. |
Id | An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null and Numbers SHOULD NOT contain fractional parts |
IdReq | Identical to |
Response | The Result is either: |
Value | Represents any valid JSON value. |
Functions
parse_request | Parse a json string, returning either: |