Package dcrjson provides primitives for working with the Decred JSON-RPC API.
When communicating via the JSON-RPC protocol, all of the commands need to be
marshalled to and from the the wire in the appropriate format. This package
provides data structures and primitives to ease this process.
In addition, it also provides some additional features such as custom command
registration, command categorization, and reflection-based help generation.
This information is not necessary in order to use this package, but it does
provide some intuition into what the marshalling and unmarshalling that is
discussed below is doing under the hood.
As defined by the JSON-RPC spec, there are effectively two forms of messages on
NOTE: Notifications are the same format except the id field is null.
For requests, the params field can vary in what it contains depending on the
method (a.k.a. command) being sent. Each parameter can be as simple as an int
or a complex structure containing many nested fields. The id field is used to
identify a request and will be included in the associated response.
When working with asynchronous transports, such as websockets, spontaneous
notifications are also possible. As indicated, they are the same as a request
object, except they have the id field set to null. Therefore, servers will
ignore requests with the id field set to null, while clients can choose to
consume or ignore them.
Unfortunately, the original Bitcoin JSON-RPC API (and hence anything compatible
with it) doesn't always follow the spec and will sometimes return an error
string in the result field with a null error for certain commands. However,
for the most part, the error field will be set as described on failure.
Based upon the discussion above, it should be easy to see how the types of this
package map into the required parts of the protocol
To simplify the marshalling of the requests and responses, the MarshalCmd and
MarshalResponse functions are provided. They return the raw bytes ready to be
sent across the wire.
Unmarshalling a received Request object is a two step process:
This approach is used since it provides the caller with access to the additional
fields in the request that are not part of the command such as the ID.
Unmarshalling a received Response object is also a two step process:
As above, this approach is used since it provides the caller with access to the
fields in the response such as the ID and Error.
This package provides two approaches for creating a new command. This first,
and preferred, method is to use one of the New<Foo>Cmd functions. This allows
static compile-time checking to help ensure the parameters stay in sync with
the struct definitions.
The second approach is the NewCmd function which takes a method (command) name
and variable arguments. The function includes full checking to ensure the
parameters are accurate according to provided method, however these checks are,
obviously, run-time which means any mistakes won't be found until the code is
actually executed. However, it is quite useful for user-supplied commands
that are intentionally dynamic.
The command handling of this package is built around the concept of registered
commands. This is true for the wide variety of commands already provided by the
package, but it also means caller can easily provide custom commands with all
of the same functionality as the built-in commands. Use the RegisterCmd
function for this purpose.
A list of all registered methods can be obtained with the RegisteredCmdMethods
All registered commands are registered with flags that identify information such
as whether the command applies to a chain server, wallet server, or is a
notification along with the method name to use. These flags can be obtained
with the MethodUsageFlags flags, and the method can be obtained with the
To facilitate providing consistent help to users of the RPC server, this package
exposes the GenerateHelp and function which uses reflection on registered
commands or notifications, as well as the provided expected result types, to
generate the final help text.
In addition, the MethodUsageText function is provided to generate consistent
one-line usage for registered commands and notifications using reflection.
There are 2 distinct type of errors supported by this package:
The first category of errors (type Error) typically indicates a programmer error
and can be avoided by properly using the API. Errors of this type will be
returned from the various functions available in this package. They identify
issues such as unsupported field types, attempts to register malformed commands,
and attempting to create a new command with an improper number of parameters.
The specific reason for the error can be detected by type asserting it to a
*dcrjson.Error and accessing the ErrorCode field.
The second category of errors (type RPCError), on the other hand, are useful for
returning errors to RPC clients. Consequently, they are used in the previously
described Response type.
This example demonstrates how to unmarshal a JSON-RPC response and then
unmarshal the result field in the response to a concrete type.