Welcome to the second blog post of this series consacred to my project of a JSON-RPC client implementation in Haskell (the first post may be consulted here).
What are the implementation choices ?
I had to choose between version 1 and version 2 of the protocol. I have chosen to implement both versions using the second version as the default protocol. The reasons for this choice were the following:
- Most other implementations support version 2, so there’s not a great incentive not to implement version 2. However, you might be forced to work with a legacy server, like I had been during my tests. Thus, having also version 1 is a Good Idea™.
- Annoyingly enough, version 1 mandates the existence of an error object but doesn’t specify required fields…
- Yet another annoyance concerns ids, version 1 specifies that a method call id is of any type but mandates that a notification id be of null type. This slight imprecision is usually dealt with by using only non-null ids as call ids, but still… To be fair, version 2 is also annoying here: a method call id is a number, a string or null but a null id must be attributed to syntactically incorrect requests. This “problem” is dealt with by, once again, using only non-null ids.
I do not, for the time being, implement batch requests (given that the API map an Haskell function call to a JSON-RPC communication), neither do I implement positional arguments, nor do I implement other transports than HTTP POST requests. I might in the future try to adapt the API to support batch requests and to support other transports (HTTP GET, TCP streams…)
What is the API ?
The API, as well as the code, was heavily inspired by HaXR (which, if you think about it is only fitting given JSON-RPC was inspired by XML-RPC)
Exposed to the client, there are two typeclasses:
JsonRpcCall (representing remote calls) and
JsonRpcNotification (representing notifications). Both serve to retrieve and marshal the remote function’s parameters, call it and, in
JsonRpcCall‘s case, retrieve and unmarshal the result. Both have an instance for functions taking an instance of
ToJSON (that is, a type marshallable to JSON, this typeclass comes from aeson) and returning an instance of the typeclass.
JsonRpcCall has also an instance for
(FromJSON a) => IO a (type unmarshallable from JSON, lifted in IO, also comes from aeson) and
JsonRpcNotification has an instance for
IO (), which is normal given a notification doesn’t care about the server answer. The IO part of the return type shouldn’t be a surprise: after all, they take their result from the network…
There are also two data types:
JsonRpcVersion representing the protocol’s version used in a given call and
JsonRpcException representing errors in JSON-RPC, be that errors in the remote functions usage, in the (un)marshalling of the messages, or even type mismatches between the remote function and its caller.
Finally, there are four functions:
notify which generate a remote call (resp. notification) using JSON-RPC version 2, HTTP POST as transport protocol and without custom elements in the generated JSON. Their signatures should always be explicit: they take two
Strings in arguments (the server’s URL and the method’s name) and return a
JsonRpcNotification). The other two are
detailledNotify which take, before the two
Strings taken by the basic versions, a
JsonRpcVersion and a
[Pair], representing respectively the protocol version used for this call and the key-element pairs to be added to the JSON object representing the request, in addition to the standards elements.
And after ?
The next blog post in this series will talk about the details of the implementation of this client, and how to use it.
In the meantime, you may find the source code of the client here.