Generating gRPC Services
Overview
Generate gRPC service definitions, client/server stubs, and implementations from Protocol Buffer (protobuf) .proto files. Scaffold unary, server-streaming, client-streaming, and bidirectional-streaming RPC methods with proper error status codes, interceptors for auth/logging, and health check service registration.
Prerequisites
- Protocol Buffers compiler (
protoc) v3.21+ installed
- Language-specific gRPC plugin:
grpctoolsnodeprotocplugin (Node.js), grpcio-tools (Python), or Go gRPC plugin
buf CLI for proto linting and breaking change detection (recommended)- gRPC testing tool:
grpcurl, evans, or BloomRPC
- TLS certificates for production transport security (mTLS recommended for service-to-service)
Instructions
- Read existing
.proto files using Glob and Read, or design new service definitions with message types, RPC methods, and streaming patterns per service requirements.
- Define proto3 message types with appropriate field types, using
google.protobuf.Timestamp for dates, google.protobuf.Struct for dynamic fields, and oneof for polymorphic messages.
- Compile
.proto files with protoc to generate language-specific stubs, server interfaces, and client libraries using the appropriate gRPC plugin.
- Implement server-side RPC handlers for each method, returning proper gRPC status codes (
OK, NOTFOUND, INVALIDARGUMENT, PERMISSION_DENIED) instead of generic errors.
- Add server interceptors for authentication (extracting JWT from metadata), request logging with correlation IDs, and deadline propagation across service calls.
- Implement health check service (
grpc.health.v1.Health) and reflection service for runtime introspection by tools like grpcurl.
- Configure TLS transport security, preferring mutual TLS (mTLS) for service-to-service communication with certificate rotation support.
- Write integration tests using an in-process test server, validating all RPC methods including streaming scenarios with multiple messages and error conditions.
- Generate a REST-to-gRPC gateway using
grpc-gateway annotations for HTTP/JSON clients that need to access gRPC services.
See ${CLAUDESKILLDIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDESKILLDIR}/proto/ - Protocol Buffer service and message definitions${CLAUDESKILLDIR}/generated/ - Auto-generated stubs and client/server code${CLAUDESKILLDIR}/src/services/ - RPC method
