[][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> and Vec<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 jsonrpc version. Will serialize/deserialize to/from "2.0".

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 Id except has the Notification type. Typically you should use Id since all functions that would accept IdReq accept Into<IdReq>.

Response

The Result is either:

Value

Represents any valid JSON value.

Functions

parse_request

Parse a json string, returning either: