btcjson: Add README.md and doc.go for btcjsonv2.
This commit is contained in:
Dave Collins
parent
122031bee3
commit
1c332b283f
2 changed files with 213 additions and 0 deletions
67
btcjson/v2/btcjson/README.md
Normal file
67
btcjson/v2/btcjson/README.md
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
btcjson
|
||||
=======
|
||||
|
||||
[]
|
||||
(https://travis-ci.org/btcsuite/btcd) [![ISC License]
|
||||
(http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org)
|
||||
|
||||
Package btcjson implements concrete types for marshalling to and from the
|
||||
bitcoin JSON-RPC API. A comprehensive suite of tests is provided to ensure
|
||||
proper functionality.
|
||||
|
||||
Although this package was primarily written for the btcsuite, it has
|
||||
intentionally been designed so it can be used as a standalone package for any
|
||||
projects needing to marshal to and from bitcoin JSON-RPC requests and responses.
|
||||
|
||||
Note that although it's possible to use this package directly to implement an
|
||||
RPC client, it is not recommended since it is only intended as an infrastructure
|
||||
package. Instead, RPC clients should use the
|
||||
[btcrpcclient](https://github.com/btcsuite/btcrpcclient) package which provides
|
||||
a full blown RPC client with many features such as automatic connection
|
||||
management, websocket support, automatic notification re-registration on
|
||||
reconnect, and conversion from the raw underlying RPC types (strings, floats,
|
||||
ints, etc) to higher-level types with many nice and useful properties.
|
||||
|
||||
## Documentation
|
||||
|
||||
[]
|
||||
(http://godoc.org/github.com/btcsuite/btcd/btcjson/v2/btcjson)
|
||||
|
||||
Full `go doc` style documentation for the project can be viewed online without
|
||||
installing this package by using the GoDoc site
|
||||
[here](http://godoc.org/github.com/btcsuite/btcd/btcjson/v2/btcjson).
|
||||
|
||||
You can also view the documentation locally once the package is installed with
|
||||
the `godoc` tool by running `godoc -http=":6060"` and pointing your browser to
|
||||
http://localhost:6060/pkg/github.com/btcsuite/btcd/btcjson/v2/btcjson
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
$ go get github.com/btcsuite/btcd/btcjson/v2/btcjson
|
||||
```
|
||||
|
||||
## GPG Verification Key
|
||||
|
||||
All official release tags are signed by Conformal so users can ensure the code
|
||||
has not been tampered with and is coming from Conformal. To verify the
|
||||
signature perform the following:
|
||||
|
||||
- Download the public key from the Conformal website at
|
||||
https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt
|
||||
|
||||
- Import the public key into your GPG keyring:
|
||||
```bash
|
||||
gpg --import GIT-GPG-KEY-conformal.txt
|
||||
```
|
||||
|
||||
- Verify the release tag with the following command where `TAG_NAME` is a
|
||||
placeholder for the specific tag:
|
||||
```bash
|
||||
git tag -v TAG_NAME
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Package btcjson is licensed under the [copyfree](http://copyfree.org) ISC
|
||||
License.
|
||||
146
btcjson/v2/btcjson/doc.go
Normal file
146
btcjson/v2/btcjson/doc.go
Normal file
|
|
@ -0,0 +1,146 @@
|
|||
// Copyright (c) 2015 Conformal Systems LLC.
|
||||
// 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
|
||||
Loading…
Reference in a new issue