decred.org/dcrwallet/v3@v3.1.0/rpc/jsonrpc/types/doc.go (about)

     1  // Copyright (c) 2019 The Decred 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 types implements concrete types for the dcrwallet JSON-RPC API.
     7  
     8  When communicating via the JSON-RPC protocol, all of the commands need to be
     9  marshalled to and from the wire in the appropriate format.  This package
    10  provides data structures and primitives that are registered with dcrjson to ease
    11  this process.  An overview specific to this package is provided here, however it
    12  is also instructive to read the documentation for the dcrjson package
    13  (https://pkg.go.dev/github.com/decred/dcrd/dcrjson/v4).
    14  
    15  # Marshalling and Unmarshalling
    16  
    17  The types in this package map to the required parts of the protocol as discussed
    18  in the dcrjson documention
    19  
    20    - Request Objects (type Request)
    21    - Commands (type <Foo>Cmd)
    22    - Notifications (type <Foo>Ntfn)
    23    - Response Objects (type Response)
    24    - Result (type <Foo>Result)
    25  
    26  To simplify the marshalling of the requests and responses, the
    27  dcrjson.MarshalCmd and dcrjson.MarshalResponse functions may be used.  They
    28  return the raw bytes ready to be sent across the wire.
    29  
    30  Unmarshalling a received Request object is a two step process:
    31   1. Unmarshal the raw bytes into a Request struct instance via json.Unmarshal
    32   2. Use UnmarshalCmd on the Result field of the unmarshalled Request to create
    33      a concrete command or notification instance with all struct fields set
    34      accordingly
    35  
    36  This approach is used since it provides the caller with access to the additional
    37  fields in the request that are not part of the command such as the ID.
    38  
    39  Unmarshalling a received Response object is also a two step process:
    40   1. Unmarshal the raw bytes into a Response struct instance via json.Unmarshal
    41   2. Depending on the ID, unmarshal the Result field of the unmarshalled
    42      Response to create a concrete type instance
    43  
    44  As above, this approach is used since it provides the caller with access to the
    45  fields in the response such as the ID and Error.
    46  
    47  # Command Creation
    48  
    49  This package provides two approaches for creating a new command.  This first,
    50  and preferred, method is to use one of the New<Foo>Cmd functions.  This allows
    51  static compile-time checking to help ensure the parameters stay in sync with
    52  the struct definitions.
    53  
    54  The second approach is the dcrjson.NewCmd function which takes a method
    55  (command) name and variable arguments.  Since this package registers all of its
    56  types with dcrjson, the function will recognize them and includes full checking
    57  to ensure the parameters are accurate according to provided method, however
    58  these checks are, obviously, run-time which means any mistakes won't be found
    59  until the code is actually executed.  However, it is quite useful for
    60  user-supplied commands that are intentionally dynamic.
    61  
    62  # Help Generation
    63  
    64  To facilitate providing consistent help to users of the RPC server, the dcrjson
    65  package exposes the GenerateHelp and function which uses reflection on commands
    66  and notifications registered by this package, as well as the provided expected
    67  result types, to generate the final help text.
    68  
    69  In addition, the dcrjson.MethodUsageText function may be used to generate
    70  consistent one-line usage for registered commands and notifications using
    71  reflection.
    72  */
    73  package types