github.com/lbryio/lbcd@v0.22.119/btcjson/doc.go (about)

     1  // Copyright (c) 2015 The btcsuite developers
     2  // Use of this source code is governed by an ISC
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  Package btcjson provides primitives for working with the bitcoin JSON-RPC API.
     7  
     8  # Overview
     9  
    10  When communicating via the JSON-RPC protocol, all of the commands need to be
    11  marshalled to and from the the wire in the appropriate format.  This package
    12  provides data structures and primitives to ease this process.
    13  
    14  In addition, it also provides some additional features such as custom command
    15  registration, command categorization, and reflection-based help generation.
    16  
    17  # JSON-RPC Protocol Overview
    18  
    19  This information is not necessary in order to use this package, but it does
    20  provide some intuition into what the marshalling and unmarshalling that is
    21  discussed below is doing under the hood.
    22  
    23  As defined by the JSON-RPC spec, there are effectively two forms of messages on
    24  the wire:
    25  
    26    - Request Objects
    27      {"jsonrpc":"1.0","id":"SOMEID","method":"SOMEMETHOD","params":[SOMEPARAMS]}
    28      NOTE: Notifications are the same format except the id field is null.
    29  
    30    - Response Objects
    31      {"result":SOMETHING,"error":null,"id":"SOMEID"}
    32      {"result":null,"error":{"code":SOMEINT,"message":SOMESTRING},"id":"SOMEID"}
    33  
    34  For requests, the params field can vary in what it contains depending on the
    35  method (a.k.a. command) being sent.  Each parameter can be as simple as an int
    36  or a complex structure containing many nested fields.  The id field is used to
    37  identify a request and will be included in the associated response.
    38  
    39  When working with asynchronous transports, such as websockets, spontaneous
    40  notifications are also possible.  As indicated, they are the same as a request
    41  object, except they have the id field set to null.  Therefore, servers will
    42  ignore requests with the id field set to null, while clients can choose to
    43  consume or ignore them.
    44  
    45  Unfortunately, the original Bitcoin JSON-RPC API (and hence anything compatible
    46  with it) doesn't always follow the spec and will sometimes return an error
    47  string in the result field with a null error for certain commands.  However,
    48  for the most part, the error field will be set as described on failure.
    49  
    50  # Marshalling and Unmarshalling
    51  
    52  Based upon the discussion above, it should be easy to see how the types of this
    53  package map into the required parts of the protocol
    54  
    55    - Request Objects (type Request)
    56    - Commands (type <Foo>Cmd)
    57    - Notifications (type <Foo>Ntfn)
    58    - Response Objects (type Response)
    59    - Result (type <Foo>Result)
    60  
    61  To simplify the marshalling of the requests and responses, the MarshalCmd and
    62  MarshalResponse functions are provided.  They return the raw bytes ready to be
    63  sent across the wire.
    64  
    65  Unmarshalling a received Request object is a two step process:
    66   1. Unmarshal the raw bytes into a Request struct instance via json.Unmarshal
    67   2. Use UnmarshalCmd on the Result field of the unmarshalled Request to create
    68      a concrete command or notification instance with all struct fields set
    69      accordingly
    70  
    71  This approach is used since it provides the caller with access to the additional
    72  fields in the request that are not part of the command such as the ID.
    73  
    74  Unmarshalling a received Response object is also a two step process:
    75   1. Unmarhsal the raw bytes into a Response struct instance via json.Unmarshal
    76   2. Depending on the ID, unmarshal the Result field of the unmarshalled
    77      Response to create a concrete type instance
    78  
    79  As above, this approach is used since it provides the caller with access to the
    80  fields in the response such as the ID and Error.
    81  
    82  # Command Creation
    83  
    84  This package provides two approaches for creating a new command.  This first,
    85  and preferred, method is to use one of the New<Foo>Cmd functions.  This allows
    86  static compile-time checking to help ensure the parameters stay in sync with
    87  the struct definitions.
    88  
    89  The second approach is the NewCmd function which takes a method (command) name
    90  and variable arguments.  The function includes full checking to ensure the
    91  parameters are accurate according to provided method, however these checks are,
    92  obviously, run-time which means any mistakes won't be found until the code is
    93  actually executed.  However, it is quite useful for user-supplied commands
    94  that are intentionally dynamic.
    95  
    96  # Custom Command Registration
    97  
    98  The command handling of this package is built around the concept of registered
    99  commands.  This is true for the wide variety of commands already provided by the
   100  package, but it also means caller can easily provide custom commands with all
   101  of the same functionality as the built-in commands.  Use the RegisterCmd
   102  function for this purpose.
   103  
   104  A list of all registered methods can be obtained with the RegisteredCmdMethods
   105  function.
   106  
   107  # Command Inspection
   108  
   109  All registered commands are registered with flags that identify information such
   110  as whether the command applies to a chain server, wallet server, or is a
   111  notification along with the method name to use.  These flags can be obtained
   112  with the MethodUsageFlags flags, and the method can be obtained with the
   113  CmdMethod function.
   114  
   115  # Help Generation
   116  
   117  To facilitate providing consistent help to users of the RPC server, this package
   118  exposes the GenerateHelp and function which uses reflection on registered
   119  commands or notifications, as well as the provided expected result types, to
   120  generate the final help text.
   121  
   122  In addition, the MethodUsageText function is provided to generate consistent
   123  one-line usage for registered commands and notifications using reflection.
   124  
   125  # Errors
   126  
   127  There are 2 distinct type of errors supported by this package:
   128  
   129    - General errors related to marshalling or unmarshalling or improper use of
   130      the package (type Error)
   131    - RPC errors which are intended to be returned across the wire as a part of
   132      the JSON-RPC response (type RPCError)
   133  
   134  The first category of errors (type Error) typically indicates a programmer error
   135  and can be avoided by properly using the API.  Errors of this type will be
   136  returned from the various functions available in this package.  They identify
   137  issues such as unsupported field types, attempts to register malformed commands,
   138  and attempting to create a new command with an improper number of parameters.
   139  The specific reason for the error can be detected by type asserting it to a
   140  *btcjson.Error and accessing the ErrorCode field.
   141  
   142  The second category of errors (type RPCError), on the other hand, are useful for
   143  returning errors to RPC clients.  Consequently, they are used in the previously
   144  described Response type.
   145  */
   146  package btcjson