-
Notifications
You must be signed in to change notification settings - Fork 0
/
doc.go
129 lines (84 loc) · 6.24 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
// 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","netparams":[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 netparams 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 BTCJSONError.
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 BTCJSONError)
- 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 BTCJSONError) 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.BTCJSONError 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