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:
grpc_tools_node_protoc_plugin(Node.js),grpcio-tools(Python), or Go gRPC plugin bufCLI 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
.protofiles 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.Timestampfor dates,google.protobuf.Structfor dynamic fields, andoneoffor polymorphic messages. - Compile
.protofiles withprotocto 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,NOT_FOUND,INVALID_ARGUMENT,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 likegrpcurl. - 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-gatewayannotations for HTTP/JSON clients that need to access gRPC services.
See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDE_SKILL_DIR}/proto/- Protocol Buffer service and message definitions${CLAUDE_SKILL_DIR}/generated/- Auto-generated stubs and client/server code${CLAUDE_SKILL_DIR}/src/services/- RPC method handler implementations${CLAUDE_SKILL_DIR}/src/interceptors/- Auth, logging, and metrics interceptors${CLAUDE_SKILL_DIR}/src/health/- Health check service implementation${CLAUDE_SKILL_DIR}/gateway/- REST-to-gRPC gateway configuration (optional)${CLAUDE_SKILL_DIR}/tests/- Integration tests with in-process test server
Error Handling
| Error | Cause | Solution |
|---|---|---|
| INVALID_ARGUMENT (3) | Request message fails field validation constraints | Return detailed BadRequest error details with field-level violation descriptions |
| NOT_FOUND (5) | Requested resource does not exist | Include resource type and ID in error message metadata for client debugging |
| PERMISSION_DENIED (7) | Caller lacks required role or scope in JWT metadata | Return required permission in error details; log denied access attempt |
| DEADLINE_EXCEEDED (4) | RPC took longer than client-specified deadline | Propagate deadlines to downstream calls; implement cascading timeout budgets |
| UNAVAILABLE (14) | Server overloaded or downstream dependency unreachable | Client should retry with exponential backoff; server should implement backpressure |
Refer to ${CLAUDE_SKILL_DIR}/references/errors.md for comprehensive error patterns.
Examples
User management service: Define UserService with CreateUser, GetUser, ListUsers (server-streaming for large result sets), and UpdateUser RPCs with field mask support for partial updates.
Real-time event stream: Bidirectional streaming RPC where clients subscribe to event topics and the server pushes filtered events, with flow control via client-side backpressure signals.
gRPC-Web frontend: Generate gRPC-Web compatible stubs for browser clients using Envoy proxy for HTTP/2 to gRPC translation, enabling direct proto-based communication from React/Vue applications.
See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.
Resources
- gRPC documentation: https://grpc.io/docs/
- Protocol Buffers Language Guide: https://protobuf.dev/programming-guides/proto3/
- Buf CLI for proto management: https://buf.build/
- gRPC-Gateway: https://grpc-ecosystem.github.io/grpc-gateway/