go-grpc

Go gRPC

Treat gRPC as a transport. Keep .proto-generated code and business logic separated. The official Go implementation is google.golang.org/grpc; pair it with protoc-gen-go + protoc-gen-go-grpc (or buf generate).

Core Rules

1. One concern per layer. .proto defines the contract; generated code lives in gen/; service implementation lives in internal/. Never edit generated files.
2. Always wrap RPC arguments in Request/Response messages. Bare scalars (string, int32) cannot be evolved without breaking callers.
3. Return typed status codes, never raw errors. A fmt.Errorf becomes codes.Unknown on the wire — the client cannot decide whether to retry.
4. Every client call has a deadline. No context.Background() to a remote service. Set context.WithTimeout per call.
5. Reuse connections. HTTP/2 multiplexes; creating a new grpc.ClientConn per request is a TLS handshake leak.
6. Disable reflection in production. Reflection is a developer convenience that doubles as an API enumeration tool for attackers.

When to Use What

Need	Use
Define service	.proto file in proto/<service>/v1/
Generate stubs	buf generate or protoc --go_out --go-grpc_out
Cross-cutting (auth, logging, recovery)	grpc.ChainUnaryInterceptor / ChainStreamInterceptor
Health probes (Kubernetes)	grpc_health_v1 from google.golang.org/grpc/health
Errors with details	status.Errorf(codes.X, ...) + WithDetails(errdetails.BadRequest{...})
Tests	google.golang.org/grpc/test/bufconn
Service mesh / mTLS	credentials.NewTLS or delegate to Istio/Linkerd

Read references/proto-and-codegen.md when organizing .proto packages or wiring buf. Read references/status-and-errors.md when mapping domain errors to gRPC codes.

Server Bootstrap

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/health"
    healthpb "google.golang.org/grpc/health/grpc_health_v1"
)

srv := grpc.NewServer(
    grpc.ChainUnaryInterceptor(recoveryUnary, loggingUnary, authUnary),
    grpc.ChainStreamInterceptor(recoveryStream, loggingStream),
)
pb.RegisterUserServiceServer(srv, &userService{...})
healthpb.RegisterHealthServer(srv, health.NewServer())

go func() { _ = srv.Serve(lis) }()

// Graceful shutdown bounded by a hard timeout.
<-shutdownSignal
stopped := make(chan struct{})
go func() { srv.GracefulStop(); close(stopped) }()
select {
case <-stopped:
case <-time.After(15 * time.Second):
    srv.Stop()
}