golang-grpc

name	golang-grpc
description	Production gRPC in Go: protobuf layout, codegen, interceptors, deadlines, error codes, streaming, health checks, TLS, and testing with bufconn
user-invocable	false
disable-model-invocation	true
version	1.0.0
category	toolchain
author	Claude MPM Team
license	MIT
progressive_disclosure	{"entry_point":{"summary":"Build production gRPC services in Go with protobuf-first APIs, interceptors, deadlines, status codes, and streaming patterns","when_to_use":"When building Go microservices that need typed RPC, streaming, low latency, or strong client/server contracts with protobuf","quick_start":"1. Define versioned protos (pkg v1) 2. Generate Go code 3. Implement server + interceptors 4. Enforce deadlines 5. Test with bufconn"},"token_estimate":{"entry":160,"full":6500}}
context_limit	900
tags	["golang","grpc","protobuf","microservices","streaming","interceptors","observability"]
requires_tools	[]

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/users/v1/users.proto
syntax = "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)

package users;

2) Generate Go code

Install generators:

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

Generate:

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
}

  GetUser(ctx context.Context, req *usersv1.GetUserRequest) (*usersv1.GetUserResponse, ) {
     req.GetId() ==  {
         , status.Error(codes.InvalidArgument, )
    }

    u, err := s.Repo.GetUser(ctx, req.GetId())
     err !=  {
         err == ErrNotFound {
             , status.Error(codes.NotFound, )
        }
         , status.Error(codes.Internal, )
    }

     &usersv1.GetUserResponse{
        User: &usersv1.User{
            Id:          u.ID,
            Email:       u.Email,
            DisplayName: u.DisplayName,
        },
    }, 
}