The gruvi.jsonrpc module implements a JSON-RPC client and server.
There are two main version of JSON-RPC: version 1.0 and version 2.0. These version are not compatible with each other. Fortunately though, it is possible to distinguish a version 1.0 from a version 2.0 message, and also the RPC model in both versions is identical. This module therefore implements both versions at the same time, in the following way:
- A reply to an incoming message will always be of the same version as the incoming message.
- A message originated by this module will use version 2.0 by default, but the default can be changed.
The “batch” feature of version 2.0 is not supported. It more relevant for JSON-RPC over HTTP rather for that clients and servers that operate directly on top of a connection.
This module provides two main classes: JsonRpcClient and JsonRpcServer. The difference is merely who initiates the connection at the transport level. The JSON-RPC protocol itself does not distinguish between clients and servers.
Both the client and the server can get incoming messages. These may be method calls (more common for servers), or notifications (in both cases). These incoming messages may be handled by providing a message handler. Providing a messasge handler is mandatory for a server while it’s optional for a client. Note that for getting regular or error returns to method calls it is not required to have a message handler. These are taken care of by the protocol implementation itself.
The signature of the message handler is: message_handler(message, protocol). Here, the message argument is a dictionary containing the parsed JSON-RPC message, while protocol is the protocol instance for the connection. The message handler is entirely responsible for dealing with the message including sending a response if applicable.
Message handlers run in a separate “distpacher” fiber, one per connection. This means that a client will have at most one dispatcher fiber, while a server will have exactly one fiber per connection. The fact that message handlers run in a separate fiber allows them to call into a switchpoint.
Exception that is raised in case of JSON-RPC protocol errors.
Exception that is raised when a error reply is received for a JSON-RPC method call.
Bases: gruvi.MessageProtocol
JSON-RPC protocol.
Send a JSON-RPC message.
The message argument must be a dictionary, and must be a valid JSON-RPC message.
This method is a switchpoint.
Send a JSON-RPC notification.
The notification method is sent with positional arguments args.
This method is a switchpoint.
Call a JSON-RPC method and wait for its result.
The method method is called with positional arguments args. On success, the 'result' attribute of the JSON-RPC response is returned. On error, an exception is raised.
This method also takes a an optional timeout keyword argument that overrides the default timeout passed to the constructor.
This method is a switchpoint.
Bases: gruvi.Client
A JSON-RPC client.
The message_handler argument specifies an optional JSON-RPC message handler. You need to use a message handler if you want to listen to notifications or you want to implement server-to-client method calls. If provided, the message handler it must be a callable with signature message_handler(message, protocol).
The version argument specifies the JSON-RPC version to use. The timeout argument specifies the default timeout in seconds.
An alias for self.protocol.call_method().
An alias for self.protocol.send_message().
An alias for self.protocol.send_notification().
Bases: gruvi.Server
A JSON-RPC server.
The message_handler argument specifies the JSON-RPC message handler. It must be a callable with signature message_handler(message, protocol). The message handler is called in a separate dispatcher fiber (one per connection).
The version argument specifies the default JSON-RPC version. The timeout argument specifies the default timeout.