ad02d8f300
This modifies the entire repository to use the new formatting of doc comments in the upcoming Go 1.19 release. The primary motivating factors for this are: - Builds check that files are formatted per gofmt and that will no longer be true as of Go 1.19 without these changes - Separating all the updates into a single commit ensures these documentation only formatting changes do not clutter up diffs that actually change code For the most part, the changes are just the automated changes suggested by the Go 1.19 version of gofmt, but there are also a few cases where the comments were reworded a bit to play nicely with the new formatting requirements. For example, the new version of gofmt reformats and collapses nested lists where as the existing version does not. Thus, instances of nested lists have been changed to either eliminate them or use mixed markers which produce expect results.
132 lines
5.9 KiB
Go
132 lines
5.9 KiB
Go
// Copyright (c) 2015 The btcsuite developers
|
|
// Copyright (c) 2015-2022 The Decred developers
|
|
// Use of this source code is governed by an ISC
|
|
// license that can be found in the LICENSE file.
|
|
|
|
/*
|
|
Package dcrjson provides infrastructure for working with Decred JSON-RPC APIs.
|
|
|
|
When communicating via the JSON-RPC protocol, all requests and responses must be
|
|
marshalled to and from the wire in the appropriate format. This package
|
|
provides infrastructure and primitives to ease this process.
|
|
|
|
# JSON-RPC Protocol Overview
|
|
|
|
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
|
|
the wire:
|
|
|
|
- Request Objects
|
|
{"jsonrpc":"1.0","id":"SOMEID","method":"SOMEMETHOD","params":[SOMEPARAMS]}
|
|
NOTE: Notifications are the same format except the id field is null.
|
|
|
|
- Response Objects
|
|
{"result":SOMETHING,"error":null,"id":"SOMEID"}
|
|
{"result":null,"error":{"code":SOMEINT,"message":SOMESTRING},"id":"SOMEID"}
|
|
|
|
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 streamed RPC 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.
|
|
|
|
# Marshalling and Unmarshalling
|
|
|
|
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:
|
|
1. Unmarshal the raw bytes into a Request struct instance via json.Unmarshal
|
|
2. Use ParseParams on the Method and Params fields of the unmarshalled Request
|
|
to create a concrete command or notification instance with all struct fields
|
|
set accordingly. The concrete types must have been registered for the method
|
|
by an external package
|
|
|
|
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:
|
|
1. Unmarshal the raw bytes into a Response struct instance via json.Unmarshal
|
|
2. Depending on the ID, unmarshal the Result field of the unmarshalled
|
|
Response to create a concrete type instance
|
|
|
|
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.
|
|
|
|
# Command Creation
|
|
|
|
This package provides 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.
|
|
|
|
External packages can and should implement types implementing Command for use
|
|
with MarshalCmd/ParseParams.
|
|
|
|
# Custom Command Registration
|
|
|
|
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
|
|
function.
|
|
|
|
# Command Inspection
|
|
|
|
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
|
|
CmdMethod function.
|
|
|
|
# Help Generation
|
|
|
|
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 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.
|
|
|
|
# Errors
|
|
|
|
There are 2 distinct type of errors supported by this package:
|
|
|
|
- General errors related to marshalling or unmarshalling or improper use of
|
|
the package (type Error)
|
|
- RPC errors which are intended to be returned across the wire as a part of
|
|
the JSON-RPC response (type RPCError)
|
|
|
|
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 ErrorKind 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.
|
|
*/
|
|
package dcrjson
|