--- name: golang-grpc-d8732f076189 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, Codex or similar harness, and for projects using Golang. metadata: author: samber version: "1.2.2" 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__* paths: - "**/*.go" --- **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 — 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`), preferred 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 ```go 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 ```go 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` ```go 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` | Create failed, entity exists | | `PermissionDenied` | Caller lacks permission | | `Unauthenticated` | Missing or invalid token | | `FailedPrecondition` | System not in required state | | `ResourceExhausted` | Rate limit or quota exceeded | | `Unavailable` | Transient issue, safe to retry | | `Internal` | Unexpected bug | | `DeadlineExceeded` | Timeout | ```go // ✗ 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 | Pattern | Use Case | | --- | --- | | Server streaming | Server sends a sequence (log tailing, result sets) | | Client streaming | Client sends a sequence, server responds once (file upload, batch) | | Bidirectional | Both send independently (chat, real-time sync) | Prefer streaming over large single messages — avoids per-message size limits and lowers memory pressure. ```go 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](references/testing.md) ## 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 | Setting | Purpose | Typical Value | | --- | --- | --- | | `keepalive.ServerParameters.Time` | Ping interval for idle connections | 30s | | `keepalive.ServerParameters.Timeout` | Ping ack timeout | 10s | | `grpc.MaxRecvMsgSize` | Override 4 MB default for large payloads | 16 MB | | Connection pooling | Multiple conns for high-load streaming | 4 connections | Most services do not need connection pooling — profile before adding complexity. ## Common Mistakes | Mistake | Fix | | --- | --- | | Returning raw `error` | Becomes `codes.Unknown` — client can't decide whether to retry. Use `status.Errorf` with a specific code | | No deadline on client calls | Slow upstream hangs indefinitely. Always `context.WithTimeout` | | New connection per request | Wastes TCP/TLS handshakes. Create once, reuse — HTTP/2 multiplexes RPCs | | Reflection enabled in production | Lets attackers enumerate every method. Enable only in dev/staging | | `codes.Internal` for all errors | Wrong codes break client retry logic. `Unavailable` triggers retry; `InvalidArgument` does not | | Bare types as RPC arguments | Can't add fields to `string`. Wrapper messages allow backwards-compatible evolution | | Missing health check service | Kubernetes can't determine readiness, kills pods during deployments | | Ignoring context cancellation | Long operations continue after caller gave up. Check `ctx.Err()` | ## 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 --- Source attribution: samber Original project: https://github.com/samber/cc-skills-golang/blob/246b6c4c1ab3077dee114beb9ade3bb0527dfebc/skills/golang-grpc/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2026 Samuel Berthe Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: samber Original project: https://github.com/samber/cc-skills-golang/blob/246b6c4c1ab3077dee114beb9ade3bb0527dfebc/skills/golang-grpc/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering Roles: Backend Developer, DevOps / SRE, ML / AI Engineer Specialties: API, Backend, Design, DevOps, Word Documents, Frontend, Git, Mobile, Testing Tools: Buf, Grpc, Protoc Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 138b8c7a6462731fcf85c2c4143a66bc5ad9078d57a664c837e9db7212a011f4