Golang Grpc

Persona: You are a Go distributed systems engineer. You design gRPC services for correctness and operability — proper status codes, deadlines, interceptors, and graceful shutdown matter as much as the happy path.

Modes:

• Build mode — implementing a new gRPC server or client from scratch.
• Review mode — auditing existing gRPC code for correctness, security, and operability issues.

Dependencies:

• protoc: brew install protobuf
• 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 gRPC Best Practices

Treat gRPC as a pure transport layer — keep it separate from business logic. The official Go implementation is google.golang.org/grpc.

This skill is not exhaustive. Please refer to library documentation and code examples for more information. Context7 can help as a discoverability platform.

Quick Reference

Proto File Organization

Organize by domain with versioned directories (proto/user/v1/). Always use Request/Response wrapper messages — bare types like string cannot have fields added later. Generate with buf generate or protoc.

Proto & code generation reference

Server Implementation

• Implement health check service (grpc_health_v1) — Kubernetes probes need it to determine readiness
• Use interceptors for cross-cutting concerns (logging, auth, recovery) — keeps business logic clean
• Use GracefulStop() with a timeout fallback to Stop() — drains in-flight RPCs while preventing hangs
• Disable reflection in production — it exposes your full API surface

srv := grpc.NewServer(
    grpc.ChainUnaryInterceptor(loggingInterceptor, recoveryInterceptor),
)
pb.RegisterUserServiceServer(srv, svc)
healthpb.RegisterHealthServer(srv, health.NewServer())

go srv.Serve(lis)

// On shutdown signal:
stopped := make(chan struct{})
go func() { srv.GracefulStop(); close(stopped) }()
select {
case <-stopped:
case <-time.After(15 * time.Second):
    srv.Stop()
}

Interceptor Pattern

func loggingInterceptor(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
    start := time.Now()
    resp, err := handler(ctx, req)
    log.Printf("method=%s duration=%s code=%s", info.FullMethod, time.Since(start), status.Code(err))
    return resp, err
}

Client Implementation

• Reuse connections — gRPC multiplexes RPCs on a single HTTP/2 connection; one-per-request wastes TCP/TLS handshakes
• Set deadlines on every call (context.WithTimeout) — without one, a slow upstream hangs goroutines indefinitely
• Use round_robin with headless Kubernetes services via dns:/// scheme
• Pass metadata (auth tokens, trace IDs) via metadata.NewOutgoingContext

conn, err := grpc.NewClient("dns:///user-service:50051",
    grpc.WithTransportCredentials(creds),
    grpc.WithDefaultServiceConfig(`{
        "loadBalancingPolicy": "round_robin",
        "methodConfig": [{
            "name": [{"service": ""}],
            "timeout": "5s",
            "retryPolicy": {
                "maxAttempts": 3,
                "initialBackoff": "0.1s",
                "maxBackoff": "1s",
                "backoffMultiplier": 2,
                "retryableStatusCodes": ["UNAVAILABLE"]
            }
        }]
    }`),
)
client := pb.NewUserServiceClient(conn)

Error Handling

Always return gRPC errors using status.Error with a specific code — a raw error becomes codes.Unknown, telling the client nothing actionable. Clients use codes to decide retry vs fail-fast vs degrade.

// ✗ Bad — caller gets codes.Unknown, can't decide whether to retry
return nil, fmt.Errorf("user not found")

// ✓ Good — specific code lets clients act appropriately
if errors.Is(err, ErrNotFound) {
    return nil, status.Errorf(codes.NotFound, "user %q not found", req.UserId)
}
return nil, status.Errorf(codes.Internal, "lookup failed: %v", err)

For field-level validation errors, attach errdetails.BadRequest via status.WithDetails.

Streaming

Prefer streaming over large single messages — avoids per-message size limits and lowers memory pressure.

func (s *server) ListUsers(req *pb.ListUsersRequest, stream pb.UserService_ListUsersServer) error {
    for _, u := range users {
        if err := stream.Send(u); err != nil {
            return err
        }
    }
    return nil
}

Testing

Use bufconn for in-memory connections that exercise the full gRPC stack (serialization, interceptors, metadata) without network overhead. Always test that error scenarios return the expected gRPC status codes.

Testing patterns and examples

Security

• TLS MUST be enabled in production — credentials travel in metadata
• For service-to-service auth, use mTLS or delegate to a service mesh (Istio, Linkerd)
• For user auth, implement credentials.PerRPCCredentials and validate tokens in an auth interceptor
• Reflection SHOULD be disabled in production to prevent API discovery

Performance

Most services do not need connection pooling — profile before adding complexity.

Common Mistakes

Cross-References

• → See samber/cc-skills-golang@golang-context skill for deadline and cancellation patterns
• → See samber/cc-skills-golang@golang-error-handling skill for gRPC error to Go error mapping
• → See samber/cc-skills-golang@golang-observability skill for gRPC interceptors (logging, tracing, metrics)
• → See samber/cc-skills-golang@golang-testing skill for gRPC testing with bufconn

Protobuf & Code Generation Reference

Directory Layout

Organize proto files by domain with versioned directories. Always use Request/Response wrapper messages — bare types like string cannot have fields added later.

proto/
├── user/v1/
│   ├── user.proto          # Messages
│   └── user_service.proto  # Service RPCs
├── order/v1/
│   ├── order.proto
│   └── order_service.proto
└── shared/v1/
    └── common.proto        # Pagination, timestamps, shared enums

Proto File Conventions

syntax = "proto3";
package mycompany.user.v1;
option go_package = "github.com/mycompany/myservice/gen/user/v1;userv1";

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
  rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);
  rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse);
}

message GetUserRequest {
  string user_id = 1;
}

message GetUserResponse {
  User user = 1;
}

message ListUsersRequest {
  int32 page_size = 1;
  string page_token = 2;
}

message ListUsersResponse {
  repeated User users = 1;
  string next_page_token = 2;
}

go_package conventions

• Format: "import/path;alias" — the alias becomes the Go package name
• Convention: lowercase version suffix (e.g. userv1, orderv1)
• Generate into a gen/ directory to keep generated code separate from hand-written code

Code Generation with protoc

# Basic generation
protoc --go_out=gen --go_opt=paths=source_relative \
       --go-grpc_out=gen --go-grpc_opt=paths=source_relative \
       proto/user/v1/*.proto

# With validation (using buf-validate)
protoc --go_out=gen --go_opt=paths=source_relative \
       --go-grpc_out=gen --go-grpc_opt=paths=source_relative \
       --validate_out="lang=go:gen" \
       proto/user/v1/*.proto

# Include external imports
protoc -I proto -I third_party \
       --go_out=gen --go_opt=paths=source_relative \
       --go-grpc_out=gen --go-grpc_opt=paths=source_relative \
       proto/user/v1/*.proto

Common protoc flags

Code Generation with buf

buf is the recommended modern alternative to raw protoc. It manages dependencies, lints protos, and generates code from a single config.

buf.gen.yaml

version: v2
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen
    opt: paths=source_relative
  - remote: buf.build/grpc/go
    out: gen
    opt: paths=source_relative

buf.yaml

version: v2
modules:
  - path: proto
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE

Common buf commands

buf generate              # Generate code from buf.gen.yaml
buf lint                  # Lint proto files
buf breaking --against '.git#branch=main'  # Check backward compatibility
buf dep update            # Update dependencies
buf build                 # Validate proto files compile

Generated Code Patterns

After generation, import and use the generated code:

import (
    userv1 "github.com/mycompany/myservice/gen/user/v1"
)

// Server: implement the interface
type userServer struct {
    userv1.UnimplementedUserServiceServer
}

// Client: use the generated client
client := userv1.NewUserServiceClient(conn)
resp, err := client.GetUser(ctx, &userv1.GetUserRequest{UserId: "123"})

Always embed Unimplemented*Server (not Unsafe*Server) — it provides forward compatibility when new RPCs are added to the proto definition.

gRPC Testing Reference

Testing with bufconn

bufconn creates in-memory connections that exercise the full gRPC stack (serialization, interceptors, metadata) without network overhead. This is the standard approach for gRPC unit and integration tests.

Basic Setup

func setupTest(t *testing.T) pb.UserServiceClient {
    t.Helper()
    lis := bufconn.Listen(1024 * 1024)
    t.Cleanup(func() { lis.Close() })

    srv := grpc.NewServer()
    pb.RegisterUserServiceServer(srv, newTestService())
    t.Cleanup(func() { srv.Stop() })
    go srv.Serve(lis)

    conn, err := grpc.NewClient("passthrough:///bufconn",
        grpc.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) {
            return lis.DialContext(ctx)
        }),
        grpc.WithTransportCredentials(insecure.NewCredentials()),
    )
    if err != nil {
        t.Fatalf("dial: %v", err)
    }
    t.Cleanup(func() { conn.Close() })
    return pb.NewUserServiceClient(conn)
}

Setup with Interceptors

Test your interceptors by including them in the test server:

func setupTestWithInterceptors(t *testing.T) pb.UserServiceClient {
    t.Helper()
    lis := bufconn.Listen(1024 * 1024)
    t.Cleanup(func() { lis.Close() })

    srv := grpc.NewServer(
        grpc.ChainUnaryInterceptor(
            loggingInterceptor,
            authInterceptor,
            recoveryInterceptor,
        ),
    )
    pb.RegisterUserServiceServer(srv, newTestService())
    t.Cleanup(func() { srv.Stop() })
    go srv.Serve(lis)

    conn, err := grpc.NewClient("passthrough:///bufconn",
        grpc.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) {
            return lis.DialContext(ctx)
        }),
        grpc.WithTransportCredentials(insecure.NewCredentials()),
    )
    if err != nil {
        t.Fatalf("dial: %v", err)
    }
    t.Cleanup(func() { conn.Close() })
    return pb.NewUserServiceClient(conn)
}

Testing Error Codes

Always verify that RPCs return the expected gRPC status codes — clients rely on codes for retry and error-handling logic.

func TestGetUser_NotFound(t *testing.T) {
    client := setupTest(t)
    _, err := client.GetUser(context.Background(), &pb.GetUserRequest{UserId: "nonexistent"})

    st, ok := status.FromError(err)
    if !ok {
        t.Fatalf("expected gRPC status error, got: %v", err)
    }
    if st.Code() != codes.NotFound {
        t.Errorf("expected NotFound, got %s: %s", st.Code(), st.Message())
    }
}

Table-Driven Error Code Tests

func TestGetUser_Errors(t *testing.T) {
    client := setupTest(t)

    tests := []struct {
        name     string
        req      *pb.GetUserRequest
        wantCode codes.Code
    }{
        {
            name:     "empty user ID",
            req:      &pb.GetUserRequest{UserId: ""},
            wantCode: codes.InvalidArgument,
        },
        {
            name:     "user not found",
            req:      &pb.GetUserRequest{UserId: "nonexistent"},
            wantCode: codes.NotFound,
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            _, err := client.GetUser(context.Background(), tt.req)
            st, ok := status.FromError(err)
            if !ok {
                t.Fatalf("expected gRPC status error, got: %v", err)
            }
            if st.Code() != tt.wantCode {
                t.Errorf("code = %s, want %s; message: %s", st.Code(), tt.wantCode, st.Message())
            }
        })
    }
}

Testing Streaming RPCs

Server Streaming

func TestListUsers_Stream(t *testing.T) {
    client := setupTest(t)
    stream, err := client.ListUsers(context.Background(), &pb.ListUsersRequest{})
    if err != nil {
        t.Fatalf("ListUsers: %v", err)
    }

    var users []*pb.User
    for {
        user, err := stream.Recv()
        if err == io.EOF {
            break
        }
        if err != nil {
            t.Fatalf("Recv: %v", err)
        }
        users = append(users, user)
    }

    if len(users) != 3 {
        t.Errorf("got %d users, want 3", len(users))
    }
}

Client Streaming

func TestBatchCreate_ClientStream(t *testing.T) {
    client := setupTest(t)
    stream, err := client.BatchCreateUsers(context.Background())
    if err != nil {
        t.Fatalf("BatchCreateUsers: %v", err)
    }

    for _, u := range testUsers {
        if err := stream.Send(u); err != nil {
            t.Fatalf("Send: %v", err)
        }
    }

    resp, err := stream.CloseAndRecv()
    if err != nil {
        t.Fatalf("CloseAndRecv: %v", err)
    }
    if resp.Created != int32(len(testUsers)) {
        t.Errorf("created = %d, want %d", resp.Created, len(testUsers))
    }
}

Testing Metadata

Verify that interceptors correctly read/write metadata:

func TestAuth_Metadata(t *testing.T) {
    client := setupTestWithInterceptors(t)

    // Without auth token → Unauthenticated
    _, err := client.GetUser(context.Background(), &pb.GetUserRequest{UserId: "1"})
    if st, _ := status.FromError(err); st.Code() != codes.Unauthenticated {
        t.Errorf("expected Unauthenticated without token, got %s", st.Code())
    }

    // With valid token → success
    md := metadata.Pairs("authorization", "Bearer valid-token")
    ctx := metadata.NewOutgoingContext(context.Background(), md)
    resp, err := client.GetUser(ctx, &pb.GetUserRequest{UserId: "1"})
    if err != nil {
        t.Fatalf("expected success with valid token: %v", err)
    }
    if resp.User == nil {
        t.Error("expected user in response")
    }
}

Testing Deadlines

func TestGetUser_DeadlineExceeded(t *testing.T) {
    client := setupTest(t) // server handler sleeps for 5s

    ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
    defer cancel()

    _, err := client.GetUser(ctx, &pb.GetUserRequest{UserId: "slow"})
    st, _ := status.FromError(err)
    if st.Code() != codes.DeadlineExceeded {
        t.Errorf("expected DeadlineExceeded, got %s", st.Code())
    }
}

Integration Test Patterns

For tests that hit real dependencies (database, external services), use build tags to separate them:

//go:build integration

func TestUserService_Integration(t *testing.T) {
    // Connect to real gRPC server
    conn, err := grpc.NewClient("localhost:50051",
        grpc.WithTransportCredentials(insecure.NewCredentials()),
    )
    if err != nil {
        t.Fatalf("dial: %v", err)
    }
    defer conn.Close()

    client := pb.NewUserServiceClient(conn)

    // Test full roundtrip
    created, err := client.CreateUser(context.Background(), &pb.CreateUserRequest{
        Name:  "integration-test",
        Email: "test@example.com",
    })
    if err != nil {
        t.Fatalf("CreateUser: %v", err)
    }

    got, err := client.GetUser(context.Background(), &pb.GetUserRequest{
        UserId: created.User.Id,
    })
    if err != nil {
        t.Fatalf("GetUser: %v", err)
    }
    if got.User.Name != "integration-test" {
        t.Errorf("name = %q, want %q", got.User.Name, "integration-test")
    }
}

Run integration tests separately:

go test -tags=integration ./...