golang-grpc

intent

you design gRPC services for correctness and operability by treating gRPC as a pure transport layer, separate from business logic. use this skill when implementing gRPC servers or clients from scratch, auditing existing gRPC code for security and operational issues, writing proto files with proper message organization, configuring interceptors for cross-cutting concerns, handling errors with specific gRPC status codes, setting up TLS/mTLS, testing with bufconn in-memory connections, or debugging streaming RPC behavior. the skill covers the official Go implementation at google.golang.org/grpc.

inputs

core dependencies (required)

• protoc: install via brew install protobuf or download from https://github.com/protocolbuffers/protobuf/releases
• protoc-gen-go: go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
• protoc-gen-go-grpc: go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
• go: version 1.19 or later

external connections and packages (required)

• google.golang.org/grpc: main gRPC library for server/client operations
• google.golang.org/protobuf: protobuf runtime and code generation
• google.golang.org/grpc/status and google.golang.org/grpc/codes: error handling with gRPC status codes
• google.golang.org/genproto/googleapis/rpc/errdetails: rich error detail messages for field-level validation
• google.golang.org/grpc/credentials: TLS/mTLS credentials and per-RPC authentication
• google.golang.org/grpc/test/bufconn: in-memory listener for testing
• google.golang.org/grpc/health: health check service implementation
• google.golang.org/grpc/metadata: context-based metadata (auth tokens, trace IDs)
• google.golang.org/grpc/reflection: service reflection (dev/staging only, disable in production)

optional but recommended

• github.com/grpc-ecosystem/go-grpc-middleware: pre-built interceptor middleware (logging, auth, recovery, validation)
• buf CLI: modern proto file linting and code generation via brew install bufbuild/buf/buf

context/environment variables (if applicable)

• GRPC_GO_LOG_VERBOSITY_LEVEL: set to 99 for debug logging during development
• GRPC_GO_LOG_SEVERITY_LEVEL: set to "info" to capture gRPC internal warnings

procedure

build mode: implementing a new gRPC server or client from scratch

step 1: define service contract in proto files

• input: domain requirements (RPC names, request/response shapes)
• organize protos in versioned directories: proto/{domain}/v1/{service}.proto
• use Request and Response wrapper messages, never bare types like string (prevents field addition in later versions)
• example: proto/user/v1/user.proto defines UserService with GetUserRequest / GetUserResponse
• output: .proto files with service definition and message types

step 2: generate Go code from proto files

• input: proto files from step 1, protoc and plugins installed
• run: protoc --go_out=. --go-grpc_out=. proto/user/v1/user.proto
• or use buf generate if using buf.yaml config
• output: generated {service}_pb.go and {service}_grpc.pb.go files with server interface and client stubs

step 3: implement server business logic

• input: generated server interface from step 2, domain logic
• create struct that satisfies the generated server interface (e.g., UserServiceServer)
• implement each RPC method to return (response, error) using status.Errorf(codes.*, "...") for gRPC errors
• output: concrete server struct with all RPC methods implemented

step 4: wire server with interceptors and health checks

• input: server implementation from step 3, interceptor functions
• create grpc.NewServer with grpc.ChainUnaryInterceptor for unary RPCs and grpc.ChainStreamInterceptor for streaming
• register health check service: healthpb.RegisterHealthServer(srv, health.NewServer())
• register your service: pb.RegisterUserServiceServer(srv, impl)
• example interceptors: logging (log method, duration, error code), recovery (catch panics), auth (validate token in metadata)
• output: initialized *grpc.Server ready to accept connections

step 5: start server listener

• input: server from step 4
• create listener: lis, err := net.Listen("tcp", ":50051")
• start in goroutine: go srv.Serve(lis)
• output: server accepting RPC traffic on :50051

step 6: implement graceful shutdown

• input: running server from step 5, shutdown signal channel (SIGTERM, SIGINT)
• on signal: call srv.GracefulStop() with timeout fallback to srv.Stop() (drain in-flight RPCs for up to 15 seconds, then forcefully stop)
• output: server shuts down cleanly, clients receive cancellation errors

step 7: implement client with connection reuse and deadlines

• input: server address (e.g., "dns:///user-service:50051" for Kubernetes), TLS credentials
• create single connection: conn, err := grpc.NewClient(target, grpc.WithTransportCredentials(creds), ...)
• apply default service config with retry policy, timeout, and load balancing
• store conn at package level or in dependency injection container (never create per-request)
• for each RPC, create fresh context with deadline: ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second); defer cancel()
• output: reusable gRPC client connection multiplexing RPCs over single HTTP/2 stream

step 8: make client RPC calls with metadata

• input: client from step 7, auth token or trace ID, context with deadline from step 7
• pass metadata via metadata.NewOutgoingContext(ctx, md) where md contains auth headers
• call RPC: resp, err := client.GetUser(ctx, &pb.GetUserRequest{UserId: id})
• check for gRPC status codes: if code := status.Code(err); code == codes.NotFound { /* handle */ }
• output: response or gRPC error with specific status code

review mode: auditing existing gRPC code

step 1: check error handling for specific status codes

• input: existing server implementation
• scan for return nil, fmt.Errorf(...) or bare error returns (bad: become codes.Unknown)
• verify each error case uses status.Errorf(codes.SpecificCode, ...) instead
• confirm error codes match intent (e.g., NotFound for missing entities, InvalidArgument for bad input, Unavailable for transient issues)
• output: list of error handling violations

step 2: verify interceptor setup

• input: server initialization code
• confirm all cross-cutting concerns (logging, auth, recovery, metrics, tracing) are in interceptors, not scattered in handler logic
• check that interceptors are chained: grpc.ChainUnaryInterceptor(logging, auth, recovery)
• output: assessment of code organization

step 3: audit client connection management

• input: client code
• search for grpc.NewClient or grpc.Dial calls inside handler functions or loops (bad: one connection per request)
• verify connection is created once and reused across all RPC calls
• confirm all client RPC calls set deadlines via context.WithTimeout
• output: connection reuse violations and missing deadline calls

step 4: check security (TLS, auth, reflection)

• input: server startup and security config
• verify TLS credentials are configured: grpc.WithTransportCredentials(creds) for client, listener uses TLS cert/key
• for service-to-service: confirm mTLS (mutual TLS) or service mesh integration
• for user-facing services: verify auth interceptor validates tokens from metadata.FromIncomingContext
• confirm reflection is not enabled in production builds (check reflection.Register calls are behind build tags or feature flags)
• output: security gaps

step 5: verify health check service

• input: server initialization
• confirm google.golang.org/grpc/health server is registered alongside main service
• output: presence/absence of health checks for Kubernetes readiness probes

step 6: validate proto message structure

• input: proto files
• confirm all RPC arguments and returns use Request/Response wrapper messages (not bare types)
• check that message fields are never removed, only marked deprecated (backwards compatibility)
• output: proto evolution violations

step 7: audit streaming RPCs for resource leaks

• input: server and client streaming implementations
• confirm stream sends/receives check for context cancellation: if ctx.Err() != nil { return ctx.Err() }
• verify no goroutines are spawned without cleanup on stream close
• output: resource leak risks

decision points

if building a new service from scratch vs auditing existing code

• choose build mode: follow procedure steps 1-8 in order for a greenfield implementation
• choose review mode: jump to audit procedure with focus areas based on codebase maturity

if using proto file organization (buf vs protoc directly)

• if small project with few proto files: use protoc directly in step 2
• if multi-package or monorepo with shared proto dependencies: adopt buf.yaml for linting, breaking change detection, and reproducible code generation

if client needs retry logic and load balancing

• if service is stateless and behind Kubernetes DNS: use dns:///service-name:port with round_robin load balancing config in step 7
• if service has sticky state: disable load balancing or implement client-side affinity (pin to specific pod)
• if transient failures are common (network blips, pod restarts): enable retry policy in service config (step 7) with backoff for UNAVAILABLE code only
• if no retries desired: omit retry policy from service config

if implementing per-RPC authentication vs service-wide

• if tokens vary per request (user auth): implement credentials.PerRPCCredentials and attach in client-side interceptor (step 8)
• if fixed service account token: pass once in connection options via grpc.WithPerRPCCredentials

if error details need field-level validation info

• if simple error: use status.Errorf(codes.InvalidArgument, "bad input") (step 3, review mode)
• if caller needs to highlight specific proto fields with errors: attach errdetails.BadRequest via status.WithDetails for rich error response

if service has large payloads or high throughput

• if messages exceed 4 MB gRPC default: override grpc.MaxRecvMsgSize and grpc.MaxSendMsgSize in server and client options
• if many concurrent small RPCs: no action required, HTTP/2 multiplexing handles it
• if few connections with large streaming payloads: connection pooling rarely needed, profile first

if debugging gRPC issues (timeouts, connection drops, serialization errors)

• enable GRPC_GO_LOG_VERBOSITY_LEVEL=99 and GRPC_GO_LOG_SEVERITY_LEVEL=info for verbose output
• check client logs for deadline exceeded or context cancelled
• verify server is returning proper gRPC status codes, not raw Go errors
• use bufconn in tests to reproduce issues in isolation (step 1 of testing procedure below)

if operating in Kubernetes vs other environments

• if Kubernetes: ensure health check service is registered for kubelet probes, use dns:/// round-robin for service discovery
• if bare VMs or local dev: hardcode IP:port, no health checks required but still recommended

if reflection should be enabled

• never in production (security risk, exposes API surface to attackers)
• always in development and staging for tooling (grpcurl, IDE extensions)
• gate behind build flag: if os.Getenv("ENABLE_REFLECTION") != "" { reflection.Register(srv) }

output contract

successful gRPC service implementation delivers

• generated Go code: {service}_pb.go (messages) and {service}_grpc.pb.go (service interface and client) in specified output directory
• server: running process listening on configured port (default :50051), accepting and responding to RPCs with proper gRPC status codes
• health check: /grpc.health.v1.Health/Check endpoint responding with SERVING status
• interceptors: all cross-cutting concerns (logging, auth, recovery) functional and producing appropriate side effects (log entries, metrics, trace spans)
• client: connection established and reused across multiple RPC calls without recreation, metadata (auth) attached to requests
• graceful shutdown: server stops accepting new RPCs within 15 seconds of shutdown signal, drains in-flight calls
• error responses: all error cases return status.Error with specific gRPC code (not codes.Unknown), clients can parse via status.Code(err) and act appropriately
• TLS/mTLS: server and client both enforce encrypted transport, certificate validation succeeds
• test coverage: bufconn-based unit tests exercise full gRPC stack and verify error codes

data format and locations:

• proto files: proto/{domain}/v{version}/{service}.proto
• generated code: same directory as proto file, or specified via --go_out flag
• config: service config embedded in grpc.NewClient options or stored in config file and loaded at startup
• logs: stdout or configured logging sink, include method name, duration, status code per interceptor
• metrics: counters and histograms for RPC count and latency, exposed via /metrics (if using Prometheus middleware)

outcome signal

you know the skill worked when

1. server starts without errors and listens on configured address
2. kubelet or health check probe receives SERVING response from grpc.health.v1.Health/Check
3. client successfully calls RPC and receives response (or proper gRPC error with specific code)
4. interceptors log every RPC with method name, duration in ms, and gRPC status code (e.g., "method=/user.v1.UserService/GetUser duration=5ms code=OK")
5. error cases return specific codes: codes.NotFound for missing entities, codes.InvalidArgument for bad input, codes.Unavailable for transient issues. client code can branch on status.Code(err) and retry only for retryable codes
6. TLS handshake succeeds on client and server, no certificate validation errors
7. graceful shutdown completes within timeout, in-flight RPCs complete or cancel cleanly, no goroutine leaks
8. bufconn tests run in-memory without network overhead and exercise interceptors, serialization, and error paths
9. streaming RPCs send and receive messages without blocking or resource leaks
10. no codes.Unknown errors appear in logs or client error handling; all errors have actionable codes