As of Sourcegraph 5.3.X, gRPC has supplanted REST as our default mode of communication between our microservices for our internal APIs.
An "internal" API is one that's solely used for intra-service communication/RPCs (think searcher fetching an archive from gitserver). Internal APIs don't include things like the GraphQL API that external people can use (including our web interface).
The internal/grpc/example package in the sourcegraph/sourcegraph monorepo contains a simple, runnable example of a gRPC service and client. It is a good starting point for understanding how to write a gRPC service that covers the following topics:
- All the basic Protobuf types (e.g. primitives, enums, messages, one-ofs, etc.)
- All the basic RPC types (e.g. unary, server streaming, client streaming, bidirectional streaming)
- Error handling (e.g. gRPC errors, wrapping status errors, etc.)
- Implementing a gRPC server (with proper separation of concerns)
- Implementing a gRPC client
- Some known footguns (non-utf8 strings, huge messages, etc.)
- Some Sourcegraph-specific helper packages and patterns (grpc/defaults, grpc/streamio, etc.)
When going through this example for the first time, it is recommended to:
- Read the protobuf definitions in weather/v1/weather.proto to get a sense of the service.
- Run the server and client examples in server/ and client/ (via server/run-server.sh and client/run-client.sh) respectively to see the service in action. You can see a recording of this below:
- Read the implementation of the server and client to get a sense of how things are implemented, and follow the explanatory comments in the code.
