go-grpc

Define the .proto contract first in versioned domain directories with Request/Response wrapper messages, then generate code with buf generate or protoc. Implement the generated server interface, register the health service, chain interceptors for cross-cutting concerns, and shut down with GracefulStop plus a timeout fallback.

Return status.Errorf with a specific code such as codes.NotFound or codes.InvalidArgument instead of a raw error, which becomes codes.Unknown. Attach errdetails.BadRequest for field-level validation failures so clients can decide between retry, fail-fast, or degrade.

buf is the recommended modern alternative to raw protoc because it manages dependencies, lints protos, and checks breaking changes from a single config. protoc works with explicit flags like --go_out and --go-grpc_out when you need direct control.

Use bufconn to create in-memory connections that exercise the full gRPC stack including serialization, interceptors, and metadata. Assert the expected status code of every error branch with status.FromError, and cover streaming RPCs by iterating Recv until io.EOF.

Calls without a deadline hang goroutines indefinitely when the upstream is slow. Set context.WithTimeout on every call, reuse a single connection since HTTP/2 multiplexes RPCs, and configure round_robin load balancing with dns:/// for headless Kubernetes services.

Use server streaming for sequences like log tailing, client streaming for uploads or batches, and bidirectional for real-time exchange. Streaming avoids the default 4 MB per-message size limit and lowers memory pressure compared to large single messages.