Grpc Service Generator

---
name: generating-grpc-services
version: 1.0.0
description: |
  Generate gRPC service definitions, stubs, and implementations from Protocol Buffers.
  Use when creating high-performance gRPC services.
  Trigger with phrases like "generate gRPC service", "create gRPC API", or "build gRPC server".
allowed-tools: Read, Write, Edit, Grep, Glob, Bash(api:grpc-*)
license: MIT
---

## Prerequisites

Before using this skill, ensure you have:
- API design specifications or requirements documented
- Development environment with necessary frameworks installed
- Database or backend services accessible for integration
- Authentication and authorization strategies defined
- Testing tools and environments configured

## Instructions

### Step 1: Design API Structure
Plan the API architecture and endpoints:
1. Use Read tool to examine existing API specifications from {baseDir}/api-specs/
2. Define resource models, endpoints, and HTTP methods
3. Document request/response schemas and data types
4. Identify authentication and authorization requirements
5. Plan error handling and validation strategies

### Step 2: Implement API Components
Build the API implementation:
1. Generate boilerplate code using Bash(api:grpc-*) with framework scaffolding
2. Implement endpoint handlers with business logic
3. Add input validation and schema enforcement
4. Integrate authentication and authorization middleware
5. Configure database connections and ORM models

### Step 3: Add API Features
Enhance with production-ready capabilities:
- Implement rate limiting and throttling policies
- Add request/response logging with correlation IDs
- Configure error handling with standardized responses
- Set up health check and monitoring endpoints
- Enable CORS and security headers

### Step 4: Test and Document
Validate API functionality:
1. Write integration tests covering all endpoints
2. Generate OpenAPI/Swagger documentation automatically
3. Create usage examples and authentication guides
4. Test with various HTTP clients (curl, Postman, REST Client)
5. Perform load testing to validate performance targets

## Output

The skill generates production-ready API artifacts:

### API Implementation
Generated code structure:
- `{baseDir}/src/routes/` - Endpoint route definitions
- `{baseDir}/src/controllers/` - Business logic handlers
- `{baseDir}/src/models/` - Data models and schemas
- `{baseDir}/src/middleware/` - Authentication, validation, logging
- `{baseDir}/src/config/` - Configuration and environment variables

### API Documentation
Comprehensive API docs including:
- OpenAPI 3.0 specification with complete endpoint definitions
- Authentication and authorization flow diagrams
- Request/response examples for all endpoints
- Error code reference with troubleshooting guidance
- SDK generation instructions for multiple languages

### Testing Artifacts
Complete test suite:
- Unit tests for individual controller functions
- Integration tests for end-to-end API workflows
- Load test scripts for performance validation
- Mock data generators for realistic testing
- Postman/Insomnia collection for manual testing

### Configuration Files
Production-ready configs:
- Environment variable templates (.env.example)
- Database migration scripts
- Docker Compose for local development
- CI/CD pipeline configuration
- Monitoring and alerting setup

## Error Handling

Common issues and solutions:

**Schema Validation Failures**
- Error: Request body does not match expected schema
- Solution: Add detailed validation error messages; provide schema documentation; implement request sanitization

**Authentication Errors**
- Error: Invalid or expired authentication tokens
- Solution: Implement proper token refresh flows; add clear error messages indicating auth failure reason; document token lifecycle

**Rate Limit Exceeded**
- Error: API consumer exceeded allowed request rate
- Solution: Return 429 status with Retry-After header; implement exponential backoff guidance; provide rate limit info in response headers

**Database Connection Issues**
- Error: Cannot connect to database or query timeout
- Solution: Implement connection pooling; add health checks; configure proper timeouts; implement circuit breaker pattern for resilience

## Resources

### API Development Frameworks
- Express.js and Fastify for Node.js APIs
- Flask and FastAPI for Python APIs
- Spring Boot for Java APIs
- Gin and Echo for Go APIs

### API Standards and Best Practices
- OpenAPI Specification 3.0+ for API documentation
- JSON:API specification for RESTful API conventions
- OAuth 2.0 and OpenID Connect for authentication
- HTTP/2 and HTTP/3 for performance optimization

### Testing and Monitoring Tools
- Postman and Insomnia for API testing
- Swagger UI for interactive API documentation
- Artillery and k6 for load testing
- Prometheus and Grafana for monitoring

### Security Best Practices
- OWASP API Security Top 10 guidelines
- JWT best practices for token-based auth
- Rate limiting strategies to prevent abuse
- Input validation and sanitization techniques