grpc.yaml

# gRPC API Code Review Guidelines
# Comprehensive rules for proto design, streaming, error handling, performance, and security

description: "Code review guidelines for gRPC API design covering protocol buffers, streaming, error handling, and best practices"
globs:
  - "**/*.proto"
  - "**/*grpc*"
  - "**/*_pb*"
  - "**/*service*"
  - "**/*.go"
  - "**/*.java"
  - "**/*.py"
  - "**/*.ts"
  - "**/*.cs"
  - "**/*.rs"

rules:
  # ============================================================================
  # PROTO DESIGN RULES
  # ============================================================================

  - name: use-consistent-proto-naming
    description: >
      Use PascalCase for message and enum names, snake_case for field names,
      PascalCase for service and RPC names. Package names should be lowercase
      with dots (com.company.service). Follow the official Protocol Buffers style guide.
    severity: medium

  - name: organize-proto-packages-logically
    description: >
      Organize protos by domain/service in separate packages. Use versioned packages
      (v1, v2) for API evolution. Keep related messages together. Import common
      types from shared packages. Avoid circular imports.
    severity: medium

  - name: ensure-backward-compatibility
    description: >
      Never change field numbers for existing fields. Never reuse deleted field
      numbers (use reserved). Don't change field types incompatibly. Add new fields
      with new numbers. Use optional for new fields to maintain compatibility.
    severity: critical

  - name: use-field-numbers-strategically
    description: >
      Reserve field numbers 1-15 for frequently used fields (they use 1 byte).
      Use reserved keyword for removed fields to prevent reuse. Plan field number
      allocation for future expansion. Document reserved ranges.
    severity: low

  - name: define-clear-message-boundaries
    description: >
      Design messages with clear boundaries and single responsibility. Avoid
      overly large messages that mix concerns. Use nested messages for related
      data. Consider message size limits (default 4MB) in design.
    severity: medium

  - name: use-well-known-types
    description: >
      Use Google's well-known types where appropriate: google.protobuf.Timestamp,
      Duration, Empty, Any, Wrapper types, FieldMask. These provide standard
      semantics and better language support than custom implementations.
    severity: medium

  # ============================================================================
  # STREAMING RULES
  # ============================================================================

  - name: choose-streaming-pattern-appropriately
    description: >
      Use unary RPCs for simple request-response. Use server streaming for large
      result sets or push notifications. Use client streaming for uploads or
      aggregation. Use bidirectional for real-time communication.
    severity: medium

  - name: implement-proper-flow-control
    description: >
      Implement backpressure handling in streaming RPCs. Don't overwhelm slow
      consumers. Use flow control settings appropriately. Monitor queue sizes.
      Consider batching messages for efficiency.
    severity: high

  - name: handle-stream-errors-gracefully
    description: >
      Handle stream errors and disconnections gracefully. Implement reconnection
      logic for long-lived streams. Use keepalive to detect dead connections.
      Clean up resources when streams end unexpectedly.
    severity: high

  - name: implement-stream-cancellation
    description: >
      Support cancellation for long-running streams. Check context cancellation
      in stream processing loops. Clean up resources on cancellation. Don't
      block cancellation with slow operations.
    severity: medium

  # ============================================================================
  # ERROR HANDLING RULES
  # ============================================================================

  - name: use-appropriate-status-codes
    description: >
      Use gRPC status codes correctly: OK, INVALID_ARGUMENT, NOT_FOUND,
      PERMISSION_DENIED, UNAUTHENTICATED, RESOURCE_EXHAUSTED, INTERNAL,
      UNAVAILABLE, DEADLINE_EXCEEDED. Map to HTTP codes consistently.
    severity: high

  - name: include-error-details
    description: >
      Use google.rpc.Status with details for rich error information. Include
      error details like BadRequest for validation errors, RetryInfo for
      retry guidance, ErrorInfo for error classification. Don't just use status message.
    severity: medium

  - name: implement-retry-logic
    description: >
      Implement retry with exponential backoff for transient errors (UNAVAILABLE,
      RESOURCE_EXHAUSTED). Respect RetryInfo from server. Don't retry non-
      idempotent operations blindly. Use retry interceptors for consistent handling.
    severity: high

  - name: distinguish-client-vs-server-errors
    description: >
      Use 4xx-equivalent codes (INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED)
      for client errors. Use 5xx-equivalent codes (INTERNAL, UNAVAILABLE) for
      server errors. Helps clients determine if retry is appropriate.
    severity: medium

  # ============================================================================
  # PERFORMANCE RULES
  # ============================================================================

  - name: manage-message-sizes
    description: >
      Keep messages reasonably sized (default limit 4MB). Stream large data
      instead of single large messages. Use compression for large payloads.
      Monitor message sizes in production.
    severity: high

  - name: propagate-deadlines
    description: >
      Always set deadlines for RPC calls. Propagate deadlines through call
      chains. Don't use infinite timeouts. Server should respect incoming
      deadlines and cancel work if deadline passed.
    severity: high

  - name: implement-client-side-load-balancing
    description: >
      Use client-side load balancing for better performance and resilience.
      Consider round-robin, pick-first, or weighted algorithms. Use service
      discovery integration. Monitor connection health.
    severity: medium

  - name: use-connection-pooling
    description: >
      Reuse gRPC channels/connections. Creating connections is expensive.
      Configure keepalive to maintain healthy connections. Use channel pools
      for high-throughput scenarios. Monitor connection count.
    severity: high

  - name: enable-compression
    description: >
      Enable gzip compression for large messages. Configure compression at
      channel or call level. Consider message size vs CPU tradeoff. Compression
      is most beneficial for text-heavy or repetitive data.
    severity: low

  # ============================================================================
  # SECURITY RULES
  # ============================================================================

  - name: always-use-tls
    description: >
      Always use TLS in production. Use mutual TLS (mTLS) for service-to-service
      communication. Properly validate certificates. Use strong cipher suites.
      Never use insecure credentials in production.
    severity: critical

  - name: implement-authentication
    description: >
      Implement proper authentication using call credentials. Use JWT tokens,
      API keys, or mTLS certificates. Validate credentials in interceptors.
      Use per-RPC credentials for token refresh scenarios.
    severity: critical

  - name: implement-authorization
    description: >
      Check authorization for each RPC. Use interceptors for common auth logic.
      Implement role-based or attribute-based access control. Log authorization
      failures. Don't expose unauthorized data in errors.
    severity: critical

  - name: validate-input-thoroughly
    description: >
      Validate all input fields in RPC handlers. Check field presence, ranges,
      formats. Return INVALID_ARGUMENT with details for validation failures.
      Don't trust client-provided data. Sanitize before use.
    severity: high

  - name: implement-rate-limiting
    description: >
      Implement rate limiting to prevent abuse and resource exhaustion. Use
      interceptors for consistent rate limiting. Return RESOURCE_EXHAUSTED
      with RetryInfo. Consider per-client and global limits.
    severity: high

  # ============================================================================
  # BEST PRACTICES RULES
  # ============================================================================

  - name: use-interceptors-for-cross-cutting-concerns
    description: >
      Use interceptors for logging, authentication, metrics, tracing, and
      error handling. Chain interceptors appropriately. Keep interceptors
      focused and composable. Avoid business logic in interceptors.
    severity: medium

  - name: implement-health-checks
    description: >
      Implement gRPC health checking protocol for load balancer integration.
      Report service and dependency health accurately. Use serving status
      appropriately (SERVING, NOT_SERVING, UNKNOWN).
    severity: high

  - name: add-observability
    description: >
      Instrument gRPC calls with metrics (latency, error rate, throughput).
      Implement distributed tracing with context propagation. Use structured
      logging with correlation IDs. Monitor connection and stream metrics.
    severity: high

  - name: document-service-contracts
    description: >
      Document services, RPCs, and messages in proto comments. Use proto
      comments for generated documentation. Document error conditions, SLAs,
      and usage examples. Keep documentation with code.
    severity: medium