/golang-grpc

name: golang-grpc
description: "Provides gRPC usage guidelines, protobuf organization, and production-ready patterns for Golang microservices. Use when implementing, reviewing, or debugging gRPC servers/clients, writing proto files, setting up interceptors, handling gRPC errors with status codes, configuring TLS/mTLS, testing with bufconn, or working with streaming RPCs."
user-invocable: true
license: MIT
compatibility: Designed for Claude Code or similar AI coding agents, and for projects using Golang.
metadata:
  author: samber
  version: "1.1.7"
  openclaw:
    emoji: "🌐"
    homepage: https://github.com/samber/cc-skills-golang
    requires:
      bins:
        - go
        - protoc
    install:
      - kind: brew
        formula: protobuf
        bins: [protoc]
allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent WebFetch mcp__context7__resolve-library-id mcp__context7__query-docs Bash(protoc:*) AskUserQuestion Bash(godig:*) Bash(gopls:*) LSP mcp__gopls__*

**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. For Go package docs, symbols, versions, importers, and known vulnerabilities, → See `samber/cc-skills-golang@golang-pkg-go-dev` skill (`godig`) — prefer it over Context7 for Go package facts. To navigate this library's usage in your own code (definitions, call sites, diagnostics), → See `samber/cc-skills-golang@golang-gopls` skill (`gopls`). Context7 remains a fallback for docs not indexed on pkg.go.dev.

Quick Reference

| Concern | Package / Tool | | --- | --- | | Service definition | `protoc` or `buf` with `.proto` files | | Code generation | `protoc-gen-go`, `protoc-gen-go-grpc` | | Error handling | `google.golang.org/grpc/status` with `codes` | | Rich error details | `google.golang.org/genproto/googleapis/rpc/errdetails` | | Interceptors | `grpc.ChainUnaryInterceptor`, `grpc.ChainStreamInterceptor` | | Middleware ecosystem | `github.com/grpc-ecosystem/go-grpc-middleware` | | Testing | `google.golang.org/grpc/test/bufconn` | | TLS / mTLS | `google.golang.org/grpc/credentials` | | Health checks | `google.golang.org/grpc/health` |

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](references/protoc-reference.md)

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.

| Code | When to Use | | -------------------- | ------------------------------------------- | | `InvalidArgument` | Malformed input (missing field, bad format) | | `NotFound` | Entity does not exist | | `AlreadyExists` | Creat