Enhance contributing/INTERNAL.md RPC documentation
- Dominant language
- Go
- Stars
- 30.1k
- Forks
- 4.6k
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 43
Description
## What is the current state of the docs?
RPCs are mentioned in the architecture section: https://github.com/hashicorp/consul/blob/master/contributing/INTERNALS.md#architecture-overview
The internal RPC endpoints are mentioned in the Server Components' section's agent/consul row https://github.com/hashicorp/consul/blob/master/contributing/INTERNALS.md#server-components
The HTTP API is mentioned in the Shared Components section under the agent/ row https://github.com/hashicorp/consul/blob/master/contributing/INTERNALS.md#shared-components
## What do we want to achieve?
We'd like to provide a simple explanation of RPC architecture to build an appropriate working knowledge for contributors. We'd also like to offer clear guidelines for using the RPC systems. Ex. what normal behavior can be expected, and what edge cases to look out for.
## How do we get there?
### Architecture
Level of detail is key here, reference things by name so users can orient themselves but stay out of implementation details that can better understood by reading the implementation itself. Stretch goal: link to implementation where appropriate.
#### Internal RPCs
- RPC lives in `agent/consul`.
- RPCs have `endpoints` and `eethods`.
- `endpoint`s are defined in `agent/consul/{name}_endpoint.go`.
- RPC server listener is started in `agent/consul/server.go` `Server.setupRPC()`
- Demultiplexing (routing) happens in `agent/consul/rpc.go`: `Server.listen`
- We listen for various requests over 8300
#### HTTP API RPCs
- If there is an `agent/consul/{name}_endpoint.go` file there is also an `agent/{name}_endpoint.go`
- and they do different things
- `agent/consul` `endpoints` are for the `msgpack`-encoded `net/rpc` style server RPCs that are only served by `server` instances
- `endpoint`s in `agent/` are API `endpoint`s that serve the json-encoded HTTP(s) API on :8500
- Most API calls just do some light validation and forward to an RPC under the covers
### Usage
#### Internal RPCs:
- Describe the `endpoint.method` format
- Show contributors an example of how to issue an RPC call to a method
- Show contributors an example of how to implement a new internal RPC `endpoint`
- Show contributors an example of how to implement a new internal RPC `method`
- Describe guidelines for creating request/response structs
- Provide examples of creating them
- Show contributors examples of how to implement a new `req` and `res` structs
- Enumerate common error cases that users are expected to handle
- Example of resolving a nil response
- Timeout
- Ensure that blocking queries should never respond with an `index` of 0
#### HTTP API RPCs:
- Example of how to issue an HTTP RPC inside of consul
- How to create new HTTP RPC endpoints
- What we value:
- Consistency with other similar APIs is better than technical correctness, e.x. API should return plain error strings not JSON error responses, pending a future redesign.
Contributor guide
Assessment
This issue has not been assessed yet.