Quoting from the spec, JSONRPC "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."
To model this agnosticism, the
jsonrpc library uses objects of a
jsonrpc-connection class, which represent a connection to a remote JSON endpoint (for details on Emacs’s object system, see EIEIO in EIEIO). In modern object-oriented parlance, this class is “abstract", i.e. the actual class of a useful connection object is always a subclass of
jsonrpc-connection. Nevertheless, we can define two distinct APIs around the
A user interface for building JSONRPC applications
In this scenario, the JSONRPC application selects a concrete subclass of
jsonrpc-connection, and proceeds to create objects of that subclass using
make-instance. To initiate a contact to the remote endpoint, the JSONRPC application passes this object to the functions
jsonrpc-async-request. For handling remotely initiated contacts, which generally come in asynchronously, the instantiation should include
:notification-dispatcherinitargs, which are both functions of 3 arguments: the connection object; a symbol naming the JSONRPC method invoked remotely; and a JSONRPC
The function passed as
:request-dispatcheris responsible for handling the remote endpoint’s requests, which expect a reply from the local endpoint (in this case, the program you’re building). Inside that function, you may either return locally (a normal return) or non-locally (an error return). A local return value must be a Lisp object that can be serialized as JSON (see Parsing JSON). This determines a success response, and the object is forwarded to the server as the JSONRPC
resultobject. A non-local return, achieved by calling the function
jsonrpc-error, causes an error response to be sent to the server. The details of the accompanying JSONRPC
errorare filled out with whatever was passed to
jsonrpc-error. A non-local return triggered by an unexpected error of any other type also causes an error response to be sent (unless you have set
debug-on-error, in which case this calls the Lisp debugger, see Error Debugging).
A inheritance interface for building JSONRPC transport implementations
In this scenario,
jsonrpc-connectionis subclassed to implement a different underlying transport strategy (for details on how to subclass, see (eieio)Inheritance.). Users of the application-building interface can then instantiate objects of this concrete class (using the
make-instancefunction) and connect to JSONRPC endpoints using that strategy.
This API has mandatory and optional parts.
To allow its users to initiate JSONRPC contacts (notifications or requests) or reply to endpoint requests, the subclass must have an implementation of the
Likewise, for handling the three types of remote contacts (requests, notifications, and responses to local requests), the transport implementation must arrange for the function
jsonrpc-connection-receiveto be called after noticing a new JSONRPC message on the wire (whatever that "wire" may be).
Finally, and optionally, the
jsonrpc-connectionsubclass should implement the
jsonrpc-running-pmethods if these concepts apply to the transport. If they do, then any system resources (e.g. processes, timers, etc.) used to listen for messages on the wire should be released in
jsonrpc-shutdown, i.e. they should only be needed while