decred.org/dcrwallet/v3@v3.1.0/rpc/documentation/serverchanges.md (about)

     1  # Making API Changes
     2  
     3  This document describes the process of how dcrwallet developers must make
     4  changes to the RPC API and server.  Due to the use of gRPC and Protocol Buffers
     5  for the RPC implementation, changes to this API require extra dependencies and
     6  steps before changes to the server can be implemented.
     7  
     8  ## Requirements
     9  
    10  - The Protocol Buffer compiler `protoc` installed with support for the `proto3`
    11    language
    12  
    13    The `protoc` tool is part of the Protocol Buffers project.  This can be
    14    installed [from source](https://github.com/google/protobuf/blob/master/src/README.md),
    15    from an [official binary release](https://github.com/google/protobuf/releases),
    16    or through an operating system's package manager.
    17  
    18  - The gRPC `protoc` plugin for Go
    19  
    20    This plugin is written in Go and is built automatically by regen.sh (discussed later).
    21  
    22  - Knowledge of Protocol Buffers version 3 (proto3)
    23  
    24  Note that a full installation of gRPC Core is not required, and only the
    25  `protoc` compiler and Go plugins are necessary.  This is due to the project
    26  using a pure Go gRPC implementation instead of wrapping the C library from gRPC
    27  Core.
    28  
    29  ## Step 1: Modify the `.proto`
    30  
    31  Once the developer dependencies have been met, changes can be made to the API by
    32  modifying the Protocol Buffers descriptor file [`api.proto`](../api.proto).
    33  
    34  The API is versioned according to the rules of [Semantic Versioning
    35  2.0](https://semver.org/).  After any changes, bump the API version in the [API
    36  specification](./api.md) and add the changes to the spec.
    37  
    38  Unless backwards compatibility is broken (and the version is bumped to represent
    39  this change), message fields must never be removed or changed, and new fields
    40  must always be appended.
    41  
    42  It is forbidden to use the `required` attribute on a message field as this can
    43  cause errors during parsing when the new API is used by an older client.
    44  Instead, the (implicit) optional attribute is used, and the server
    45  implementation must return an appropriate error if the new request field is not
    46  set to a valid value.
    47  
    48  ## Step 2: Compile the `.proto`
    49  
    50  Once changes to the descriptor file and API specification have been made, the
    51  `protoc` compiler must be used to compile the descriptor into a Go package.
    52  This code contains interfaces (stubs) for each service (to be implemented by the
    53  wallet) and message types used for each RPC.  This same code can also be
    54  imported by a Go client that then calls same interface methods to perform RPC
    55  with the wallet.
    56  
    57  By committing the autogenerated package to the project repo, the `proto3`
    58  compiler and plugin are not needed by users installing the project by source or
    59  by other developers not making changes to the RPC API.
    60  
    61  A `sh` shell script is included to compile the Protocol Buffers descriptor.  It
    62  must be run from the `rpc` directory.
    63  
    64  ```bash
    65  $ sh regen-docker.sh
    66  ```
    67  
    68  This runs `protoc` inside a `docker` container, which is optimal when the dependencies of 
    69  the `protoc3` toolchain are not installed locally. (`./regen.sh` runs 
    70  `protoc` directly, for when they are.)
    71  
    72  If a `sh` shell is unavailable, the command can be run manually instead (again
    73  from the `rpc` directory).
    74  
    75  ```
    76  protoc -I. api.proto --go_out=plugins=grpc:walletrpc
    77  ```
    78  
    79  TODO(jrick): This step could be simplified and be more portable by putting the
    80  commands in a Go source file and executing them with `go generate`.  It should,
    81  however, only be run when API changes are performed (not with `go generate
    82  ./...` in the project root) since not all developers are expected to have
    83  `protoc` installed.
    84  
    85  ## Step 3: Implement the API change in the RPC server
    86  
    87  After the Go code for the API has been regenated, the necessary changes can be
    88  implemented in the [`rpcserver`](../rpcserver/) package.
    89  
    90  ## Additional Resources
    91  
    92  - [Protocol Buffers Language Guide (proto3)](https://developers.google.com/protocol-buffers/docs/proto3)
    93  - [Protocol Buffers Basics: Go](https://developers.google.com/protocol-buffers/docs/gotutorial)
    94  - [gRPC Basics: Go](https://www.grpc.io/docs/tutorials/basic/go.html)