146 lines
6.4 KiB
Go
146 lines
6.4 KiB
Go
// Copyright (c) 2015 The btcsuite developers
|
|
// Use of this source code is governed by an ISC
|
|
// license that can be found in the LICENSE file.
|
|
|
|
/*
|
|
Package btcjson provides primitives for working with the bitcoin JSON-RPC API.
|
|
|
|
# Overview
|
|
|
|
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.
|
|
|
|
# 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 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.
|
|
|
|
# Marshalling and Unmarshalling
|
|
|
|
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
|
|
|
|
- Request Objects (type Request)
|
|
- Commands (type <Foo>Cmd)
|
|
- Notifications (type <Foo>Ntfn)
|
|
- Response Objects (type Response)
|
|
- Result (type <Foo>Result)
|
|
|
|
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 UnmarshalCmd on the Result field of the unmarshalled Request to create
|
|
a concrete command or notification instance with all struct fields set
|
|
accordingly
|
|
|
|
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. Unmarhsal 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 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.
|
|
|
|
# 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, 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.
|
|
|
|
# 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
|
|
*btcjson.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.
|
|
*/
|
|
package btcjson
|