Golang Grpc

by bobmatnyc718070a7d622MIT77 starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 2 months ago

Production gRPC in Go: protobuf layout, codegen, interceptors, deadlines, error codes, streaming, health checks, TLS, and testing with bufconn

Instructions onlySoftware Development

AI-generated overview

Guides production gRPC service development in Go, covering protobuf layout, codegen, interceptors, deadlines, streaming, TLS and testing.

What it does: This skill provides reference guidance for building production gRPC services in Go. It covers versioned protobuf API layout, code generation commands, server implementation with status codes and deadlines, interceptors, streaming patterns, health checks, graceful shutdown, TLS, and in-memory testing with bufconn. It produces instructional examples and code patterns rather than runnable artifacts.
When to use it: Use it when building Go microservices that need typed RPC, streaming, low latency, or strong client/server contracts with protobuf. It is also useful for hardening existing gRPC services with deadlines, error codes, interceptors, and tests.
Requirements: No scripts are included; it is instructions only. Following the guidance assumes a Go toolchain, protoc with protoc-gen-go and protoc-gen-go-grpc, and gRPC/protobuf Go modules; TLS examples need certificate and key files.

Go gRPC (Production)

Overview

gRPC provides strongly-typed RPC APIs backed by Protocol Buffers, with first-class streaming support and excellent performance for service-to-service communication. This skill focuses on production defaults: versioned protos, deadlines, error codes, interceptors, health checks, TLS, and testability.

Quick Start

1) Define a versioned protobuf API

✅ Correct: versioned package

proto

// proto/users/v1/users.protosyntax = "proto3";
package users.v1;option go_package = "example.com/myapp/gen/users/v1;usersv1";
service UsersService {  rpc GetUser(GetUserRequest) returns (GetUserResponse);  rpc ListUsers(ListUsersRequest) returns (stream User);}
message GetUserRequest { string id = 1; }message GetUserResponse { User user = 1; }message ListUsersRequest { int32 page_size = 1; string page_token = 2; }
message User {  string id = 1;  string email = 2;  string display_name = 3;}

// proto/users/v1/users.protosyntax = "proto3";
package users.v1;option go_package = "example.com/myapp/gen/users/v1;usersv1";
service UsersService {  rpc GetUser(GetUserRequest) returns (GetUserResponse);  rpc ListUsers(ListUsersRequest) returns (stream User);}
message GetUserRequest { string id = 1; }message GetUserResponse { User user = 1; }message ListUsersRequest { int32 page_size = 1; string page_token = 2; }
message User {  string id = 1;  string email = 2;  string display_name = 3;}

❌ Wrong: unversioned package (hard to evolve)

2) Generate Go code

Install generators:

bash

go install google.golang.org/protobuf/cmd/protoc-gen-go@latestgo install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

go install google.golang.org/protobuf/cmd/protoc-gen-go@latestgo install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Generate:

bash

protoc -I proto \  --go_out=./gen --go_opt=paths=source_relative \  --go-grpc_out=./gen --go-grpc_opt=paths=source_relative \  proto/users/v1/users.proto

protoc -I proto \  --go_out=./gen --go_opt=paths=source_relative \  --go-grpc_out=./gen --go-grpc_opt=paths=source_relative \  proto/users/v1/users.proto

3) Implement server with deadlines and status codes

✅ Correct: validate + map errors to gRPC codes

package usersvc
import (    "context"
    "google.golang.org/grpc/codes"    "google.golang.org/grpc/status"
    usersv1 "example.com/myapp/gen/users/v1")
type Service struct {    usersv1.UnimplementedUsersServiceServer    Repo Repo}
type Repo interface {    GetUser(ctx context.Context, id string) (User, error)}
type User struct {    ID, Email, DisplayName string}
func (s *Service) GetUser(ctx context.Context, req *usersv1.GetUserRequest) (*usersv1.GetUserResponse, error) {    if req.GetId() == "" {        return nil, status.Error(codes.InvalidArgument, "id is required")    }
    u, err := s.Repo.GetUser(ctx, req.GetId())    if err != nil {        if err == ErrNotFound {            return nil, status.Error(codes.NotFound, "user not found")        }        return nil, status.Error(codes.Internal, "internal error")    }
    return &usersv1.GetUserResponse{        User: &usersv1.User{            Id:          u.ID,            Email:       u.Email,            DisplayName: u.DisplayName,        },    }, nil}

package usersvc
import (    "context"
    "google.golang.org/grpc/codes"    "google.golang.org/grpc/status"
    usersv1 "example.com/myapp/gen/users/v1")
type Service struct {    usersv1.UnimplementedUsersServiceServer    Repo Repo}
type Repo interface {    GetUser(ctx context.Context, id string) (User, error)}
type User struct {    ID, Email, DisplayName string}
func (s *Service) GetUser(ctx context.Context, req *usersv1.GetUserRequest) (*usersv1.GetUserResponse, error) {    if req.GetId() == "" {        return nil, status.Error(codes.InvalidArgument, "id is required")    }
    u, err := s.Repo.GetUser(ctx, req.GetId())    if err != nil {        if err == ErrNotFound {            return nil, status.Error(codes.NotFound, "user not found")        }        return nil, status.Error(codes.Internal, "internal error")    }
    return &usersv1.GetUserResponse{        User: &usersv1.User{            Id:          u.ID,            Email:       u.Email,            DisplayName: u.DisplayName,        },    }, nil}

❌ Wrong: return raw errors (clients lose code semantics)

Core Concepts

Deadlines and cancellation

Make every call bounded; enforce server-side timeouts for expensive handlers.

✅ Correct: require deadline

if _, ok := ctx.Deadline(); !ok {    return nil, status.Error(codes.InvalidArgument, "deadline required")}

if _, ok := ctx.Deadline(); !ok {    return nil, status.Error(codes.InvalidArgument, "deadline required")}

Metadata

Use metadata for auth/session correlation, not for primary request data.

✅ Correct: read auth token from metadata

md, _ := metadata.FromIncomingContext(ctx)auth := ""if vals := md.Get("authorization"); len(vals) > 0 {    auth = vals[0]}

md, _ := metadata.FromIncomingContext(ctx)auth := ""if vals := md.Get("authorization"); len(vals) > 0 {    auth = vals[0]}

Interceptors (Middleware)

Use interceptors for cross-cutting concerns: auth, logging, metrics, tracing, request IDs.

✅ Correct: unary interceptor with request ID

func unaryRequestID() grpc.UnaryServerInterceptor {    return func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {        id := uuid.NewString()        ctx = context.WithValue(ctx, requestIDKey{}, id)        resp, err := handler(ctx, req)        return resp, err    }}

func unaryRequestID() grpc.UnaryServerInterceptor {    return func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {        id := uuid.NewString()        ctx = context.WithValue(ctx, requestIDKey{}, id)        resp, err := handler(ctx, req)        return resp, err    }}

Streaming patterns

Server streaming (paginate or stream results)

✅ Correct: stop on ctx.Done()

func (s *Service) ListUsers(req *usersv1.ListUsersRequest, stream usersv1.UsersService_ListUsersServer) error {    users, err := s.Repo.ListUsers(stream.Context(), int(req.GetPageSize()))    if err != nil {        return status.Error(codes.Internal, "internal error")    }
    for _, u := range users {        select {        case <-stream.Context().Done():            return stream.Context().Err()        default:        }
        if err := stream.Send(&usersv1.User{            Id:          u.ID,            Email:       u.Email,            DisplayName: u.DisplayName,        }); err != nil {            return err        }    }    return nil}

func (s *Service) ListUsers(req *usersv1.ListUsersRequest, stream usersv1.UsersService_ListUsersServer) error {    users, err := s.Repo.ListUsers(stream.Context(), int(req.GetPageSize()))    if err != nil {        return status.Error(codes.Internal, "internal error")    }
    for _, u := range users {        select {        case <-stream.Context().Done():            return stream.Context().Err()        default:        }
        if err := stream.Send(&usersv1.User{            Id:          u.ID,            Email:       u.Email,            DisplayName: u.DisplayName,        }); err != nil {            return err        }    }    return nil}

Unary vs streaming decision

Use unary for single request/response and simple retries.
Use server streaming for large result sets or continuous updates.
Use client streaming for bulk uploads with one final response.
Use bidirectional streaming for interactive protocols.

Production Hardening

Health checks and reflection

Add health service; enable reflection only in non-production environments.

✅ Correct: health + conditional reflection

hs := health.NewServer()grpc_health_v1.RegisterHealthServer(s, hs)
if env != "production" {    reflection.Register(s)}

hs := health.NewServer()grpc_health_v1.RegisterHealthServer(s, hs)
if env != "production" {    reflection.Register(s)}

Graceful shutdown

Prefer GracefulStop with a deadline.

✅ Correct: graceful stop

stopped := make(chan struct{})go func() {    grpcServer.GracefulStop()    close(stopped)}()
select {case <-stopped:case <-time.After(10 * time.Second):    grpcServer.Stop()}

stopped := make(chan struct{})go func() {    grpcServer.GracefulStop()    close(stopped)}()
select {case <-stopped:case <-time.After(10 * time.Second):    grpcServer.Stop()}

TLS

Use TLS (or mTLS) in production; avoid insecure credentials outside local dev.

✅ Correct: server TLS

creds, err := credentials.NewServerTLSFromFile("server.crt", "server.key")if err != nil { return err }
grpcServer := grpc.NewServer(grpc.Creds(creds))

creds, err := credentials.NewServerTLSFromFile("server.crt", "server.key")if err != nil { return err }
grpcServer := grpc.NewServer(grpc.Creds(creds))

Testing (bufconn)

Test gRPC handlers without opening real sockets using bufconn.

✅ Correct: in-memory gRPC test server

const bufSize = 1024 * 1024
lis := bufconn.Listen(bufSize)srv := grpc.NewServer()usersv1.RegisterUsersServiceServer(srv, &Service{Repo: repo})
go func() { _ = srv.Serve(lis) }()
ctx := context.Background()conn, err := grpc.DialContext(    ctx,    "bufnet",    grpc.WithContextDialer(func(context.Context, string) (net.Conn, error) { return lis.Dial() }),    grpc.WithTransportCredentials(insecure.NewCredentials()),)if err != nil { t.Fatal(err) }defer conn.Close()
client := usersv1.NewUsersServiceClient(conn)resp, err := client.GetUser(ctx, &usersv1.GetUserRequest{Id: "1"})_ = resp_ = err

const bufSize = 1024 * 1024
lis := bufconn.Listen(bufSize)srv := grpc.NewServer()usersv1.RegisterUsersServiceServer(srv, &Service{Repo: repo})
go func() { _ = srv.Serve(lis) }()
ctx := context.Background()conn, err := grpc.DialContext(    ctx,    "bufnet",    grpc.WithContextDialer(func(context.Context, string) (net.Conn, error) { return lis.Dial() }),    grpc.WithTransportCredentials(insecure.NewCredentials()),)if err != nil { t.Fatal(err) }defer conn.Close()
client := usersv1.NewUsersServiceClient(conn)resp, err := client.GetUser(ctx, &usersv1.GetUserRequest{Id: "1"})_ = resp_ = err

Anti-Patterns

Ignore deadlines: unbounded handlers cause tail latency and resource exhaustion.
Return string errors: map domain errors to codes.* with status.Error or status.Errorf.
Stream without backpressure: stop on ctx.Done() and handle Send errors.
Expose reflection in production: treat reflection as a discovery surface.

Troubleshooting

Symptom: clients see `UNKNOWN` errors

Actions:

Return status.Error(codes.X, "...") instead of raw errors.
Wrap domain errors into typed errors, then map to gRPC codes.

Symptom: slow/hanging requests

Actions:

Require deadlines and propagate ctx to downstream calls.
Add server-side timeouts and bounded concurrency in repositories.

Symptom: flaky streaming

Actions:

Stop streaming on ctx.Done() and handle stream.Send errors.
Avoid buffering entire result sets before sending.

Resources

gRPC Go: https://github.com/grpc/grpc-go
Protobuf Go: https://pkg.go.dev/google.golang.org/protobuf
gRPC error codes: https://grpc.io/docs/guides/error/

Source and attribution

Source:bobmatnyc/claude-mpm-skillsintoolchains/golang/golang-grpcat commit718070a

License: MIT

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Golang Grpc

Go gRPC (Production)

Overview

Quick Start

1) Define a versioned protobuf API

2) Generate Go code

3) Implement server with deadlines and status codes

Core Concepts

Deadlines and cancellation

Metadata

Interceptors (Middleware)

Streaming patterns

Server streaming (paginate or stream results)

Unary vs streaming decision

Production Hardening

Health checks and reflection

Graceful shutdown

TLS

Testing (bufconn)

Anti-Patterns

Troubleshooting

Symptom: clients see `UNKNOWN` errors

Symptom: slow/hanging requests

Symptom: flaky streaming

Resources

Source and attribution

More from bobmatnyc/claude-mpm-skills

Wordpress Security Validation

Bug Fix

Threat Modeling

Webapp Testing

Opentelemetry

Skill Creator

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices

Golang Grpc

Go gRPC (Production)

Overview

Quick Start

1) Define a versioned protobuf API

2) Generate Go code

3) Implement server with deadlines and status codes

Core Concepts

Deadlines and cancellation

Metadata

Interceptors (Middleware)

Streaming patterns

Server streaming (paginate or stream results)

Unary vs streaming decision

Production Hardening

Health checks and reflection

Graceful shutdown

TLS

Testing (bufconn)

Anti-Patterns

Troubleshooting

Symptom: clients see UNKNOWN errors

Symptom: slow/hanging requests

Symptom: flaky streaming

Resources

Source and attribution

More from bobmatnyc/claude-mpm-skills

Wordpress Security Validation

Bug Fix

Threat Modeling

Webapp Testing

Opentelemetry

Skill Creator

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices

Symptom: clients see `UNKNOWN` errors