Stage 3 · Build

Observability & Networking

gRPC & Protobuf

Unary/streaming, interceptors, reflection, and grpcurl for service communication.

7 min readGo for SREBuild

Protocol Buffers

Protocol Buffers define your service API and data structures. They are compiled to Go code, providing type-safe serialization and a clear contract between client and server.

service.proto


syntax = "proto3";
package myapp.v1;
option go_package = "github.com/myorg/myapp/proto/myapp/v1;myappv1";

service ConfigService {
  rpc GetConfig(GetConfigRequest) returns (Config);
  rpc ListConfigs(ListConfigsRequest) returns (ListConfigsResponse);
  rpc WatchConfig(WatchConfigRequest) returns (stream Config);
}

message GetConfigRequest {
  string name = 1;
  string namespace = 2;
}

message Config {
  string name = 1;
  string namespace = 2;
  map<string, string> data = 3;
  int64 version = 4;
}

message ListConfigsRequest {
  string namespace = 1;
  int32 page_size = 2;
  string page_token = 3;
}

message ListConfigsResponse {
  repeated Config configs = 1;
  string next_page_token = 2;
}

Proto3 syntax defines message types and service RPCs. Each field has a number for wire format compatibility. map fields create key-value pairs. stream keyword enables server-side streaming. go_package tells protoc where to generate Go code.

Generate Go code


# Install protoc and plugins
brew install protobuf
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# Generate code
protoc --go_out=. --go-grpc_out=. proto/myapp/v1/service.proto

# Or use buf (recommended)
buf generate

protoc generates Go structs from proto messages and gRPC service interfaces from proto services. buf is a modern alternative that handles module management, linting, and breaking change detection.

gRPC Server

Implement the generated server interface to handle gRPC requests. The server registers with a gRPC server and starts listening for connections.

Gogrpc-server-implementation.go

33 linesLn 1, Col 1Go

Embed UnimplementedConfigServer for forward compatibility. Use status.Errorf to return gRPC status codes. reflection.Register enables service discovery for grpcurl. Always register reflection in development.

gRPC Client

gRPC clients connect to servers and call RPC methods. Use WithBlock to wait for connection, and WithReturnConnectionError for better error messages.

Gogrpc-client.go

26 linesLn 1, Col 1Go

Dial creates a connection. NewConfigServiceClient creates a typed client. Unary RPCs are simple request-response. Check gRPC status codes for error handling — they are more expressive than HTTP status codes.

Interceptors

Interceptors are middleware for gRPC. They handle cross-cutting concerns: logging, authentication, metrics, rate limiting, and tracing.

Gogrpc-interceptors.go

49 linesLn 1, Col 1Go

Server interceptors wrap handler execution. Client interceptors wrap RPC calls. ChainUnaryInterceptor chains multiple interceptors. The order matters — first interceptor wraps the second, which wraps the third.

Streaming RPCs

Streaming RPCs send continuous data. Server streaming sends a stream of responses. Client streaming sends a stream of requests. Bidirectional streaming sends both.

Goserver-streaming.go

43 linesLn 1, Col 1Go

Server streaming sends multiple messages. Send pushes to the client. The client calls Recv in a loop until io.EOF. Client context cancellation closes the stream. Always handle the context cancellation case.

grpcurl

grpcurl is a command-line tool for interacting with gRPC servers. It is like curl for gRPC. Use it for testing, debugging, and exploration.

grpcurl examples


# List services
grpcurl -plaintext localhost:50051 list

# Describe a service
grpcurl -plaintext localhost:50051 describe myapp.v1.ConfigService

# Call a unary RPC
grpcurl -plaintext -d '{"name":"my-config","namespace":"default"}' \
  localhost:50051 myapp.v1.ConfigService/GetConfig

# Call with metadata
grpcurl -plaintext -H "authorization: Bearer $TOKEN" \
  -d '{"name":"my-config"}' \
  localhost:50051 myapp.v1.ConfigService/GetConfig

# Server streaming
grpcurl -plaintext -d '{"namespace":"default"}' \
  localhost:50051 myapp.v1.ConfigService/WatchConfig

grpcurl requires reflection or a proto file. -plaintext disables TLS. -d passes JSON request body. -H adds headers. Watch for the full method name: package.Service/Method. grpcurl is essential for debugging gRPC services.

Always enable reflection in development

reflection.Register(srv) makes your service discoverable by grpcurl. Without it, you need proto files to interact with the server. Always enable reflection in development and disable it in production.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.