Grpc

gRPC and Protocol Buffers Rules

1. Proto3 Schema Design

See references/proto-style-guide.md for detailed naming conventions, versioning, and backward compatibility rules.

Basic Rules

• Always use syntax = "proto3"; — proto2 is legacy and should not be used for new services
• Define a package that mirrors the directory structure (e.g., package com.example.order.v1;)
• Set option java_multiple_files = true; to generate one Java/Kotlin class per message
• Set option java_package to match your project's package convention
• Use google.protobuf well-known types (Timestamp, Duration, Empty, FieldMask) instead of custom equivalents
• Keep .proto files in a shared, versioned repository or module accessible to both client and server

Message Design

syntax = "proto3";

package com.example.order.v1;

import "google/protobuf/timestamp.proto";

option java_multiple_files = true;
option java_package = "com.example.order.v1";

message Order {
  string order_id = 1;
  string user_id = 2;
  OrderStatus status = 3;
  repeated OrderItem items = 4;
  google.protobuf.Timestamp created_at = 5;
  google.protobuf.Timestamp updated_at = 6;
}

message OrderItem {
  string product_id = 1;
  int32 quantity = 2;
  int64 price_cents = 3;  // Use smallest currency unit to avoid floating point
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;  // Always define zero value as UNSPECIFIED
  ORDER_STATUS_CREATED = 1;
  ORDER_STATUS_CONFIRMED = 2;
  ORDER_STATUS_SHIPPED = 3;
  ORDER_STATUS_DELIVERED = 4;
  ORDER_STATUS_CANCELLED = 5;
}

Schema Design Rules

• Never reuse or reassign field numbers — deleted fields should use reserved
• Enum zero value must always be UNSPECIFIED or UNKNOWN — it is the default
• Prefix enum values with the enum name in UPPER_SNAKE_CASE (e.g., ORDER_STATUS_CREATED)
• Use int64 or fixed-point integers for monetary values — never use float or double
• Use repeated for collections — it defaults to empty list, not null
• Use oneof for mutually exclusive fields
• Use google.protobuf.FieldMask for partial updates instead of nullable wrappers

2. Service Definition Patterns

Communication Types

Service Definition Example

service OrderService {
  // Unary — simple request/response
  rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
  rpc GetOrder(GetOrderRequest) returns (Order);

  // Server streaming — server pushes multiple responses
  rpc ListOrders(ListOrdersRequest) returns (stream Order);

  // Client streaming — client sends multiple requests
  rpc BatchCreateOrders(stream CreateOrderRequest) returns (BatchCreateOrdersResponse);

  // Bidirectional streaming — both sides stream
  rpc OrderUpdates(stream OrderUpdateRequest) returns (stream OrderUpdateResponse);
}

message CreateOrderRequest {
  string user_id = 1;
  repeated OrderItem items = 2;
}

message CreateOrderResponse {
  Order order = 1;
}

message GetOrderRequest {
  string order_id = 1;
}

message ListOrdersRequest {
  string user_id = 1;
  int32 page_size = 2;
  string page_token = 3;  // Cursor-based pagination
}

Service Definition Rules

• Use Create, Get, List, Update, Delete as standard method prefixes following Google API Design Guide conventions
• Request and response messages should be named {MethodName}Request and {MethodName}Response
• Use cursor-based pagination (page_size + page_token) for List methods
• Prefer unary RPCs unless streaming is genuinely needed — streaming adds complexity
• Use server streaming for large result sets or real-time push scenarios
• Use client streaming for batch ingestion or uploads
• Use bidirectional streaming only for true real-time bidirectional communication

3. gRPC Status Codes

Status Code Usage Guide

Status Code Rules

• Return INVALID_ARGUMENT for client input validation errors, not INTERNAL
• Return NOT_FOUND only when the resource is expected to exist — use INVALID_ARGUMENT for malformed identifiers
• Return UNAVAILABLE for transient failures that clients can retry — use INTERNAL for permanent server errors
• Return FAILED_PRECONDITION when the operation cannot proceed due to current system state
• Use UNAUTHENTICATED for missing/invalid credentials; use PERMISSION_DENIED for valid credentials with insufficient access
• Attach error details using google.rpc.Status with google.rpc.ErrorInfo, google.rpc.BadRequest, or google.rpc.DebugInfo
• Never expose stack traces or internal details in production error messages

See references/error-handling-retry.md for rich error model implementation and retry/hedging JSON configuration examples.

4. Interceptor Patterns

Common Interceptor Use Cases

See references/interceptor-patterns.md for server and client interceptor implementation examples (authentication, deadline propagation).

Interceptor Rules

• Apply interceptors in a consistent order: authentication -> authorization -> logging -> metrics -> tracing
• Server interceptors should fail fast — reject unauthenticated requests before processing
• Client interceptors should propagate deadlines and trace context to downstream services
• Never log request/response payloads in production — log metadata only (method, status, duration)
• Use Context to pass interceptor-extracted values (e.g., principal) to service implementations
• Register interceptors globally on the server/channel, not per-method

5. Deadline and Timeout Management

See references/kotlin-conventions.md for deadline configuration code examples (client-side and server-side).

Deadline vs Timeout

Deadline Rules

• Always set deadlines on client calls — never allow unbounded calls
• Deadlines propagate automatically through the gRPC context across service hops
• Set downstream service deadlines shorter than the caller's remaining deadline
• Check Context.current().isCancelled before starting expensive operations
• Use a default deadline interceptor to ensure no call goes without a deadline
• Log deadline exceeded events — they indicate capacity or latency issues

Recommended Timeout Strategy

6. Load Balancing Strategies

Load Balancing Models

Client-Side Load Balancing

// Round-robin load balancing with name resolver
val channel = ManagedChannelBuilder
    .forTarget("dns:///order-service:50051")
    .defaultLoadBalancingPolicy("round_robin")
    .usePlaintext()  // For development only — use TLS in production
    .build()

Load Balancing Rules

• Use round_robin for Kubernetes headless services — it resolves all pod IPs
• Use proxy-based load balancing (e.g., Envoy) when client-side LB is not feasible
• In service mesh environments, delegate load balancing to the sidecar proxy
• Enable health checking on the client to avoid sending requests to unhealthy backends
• For gRPC, prefer L7 (HTTP/2-aware) load balancers over L4 — L4 balancers pin connections to one backend
• Configure keepAliveTime and keepAliveTimeout to detect dead connections

Kubernetes Considerations

# Headless service for client-side load balancing
apiVersion: v1
kind: Service
metadata:
  name: order-service
spec:
  clusterIP: None  # Headless — DNS returns all pod IPs
  selector:
    app: order-service
  ports:
    - port: 50051
      targetPort: 50051
      protocol: TCP

7. Error Handling and Retry Policy

Retry Rules

• Only retry on transient status codes: UNAVAILABLE, DEADLINE_EXCEEDED, ABORTED
• Never retry INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, or UNAUTHENTICATED — these are permanent failures
• Use exponential backoff with jitter to avoid thundering herd
• Set maxAttempts to 3-5 — more retries rarely help and increase load
• Ensure operations are idempotent before enabling retries — or use idempotency keys
• Use hedging (sending parallel requests) only for read-only operations with low cost
• gRPC built-in retry is configured via service config JSON — prefer it over application-level retry

8. gRPC-Java and gRPC-Kotlin Conventions

See references/kotlin-conventions.md for coroutine stub usage, extension patterns, and proto-to-domain mapping examples.

Convention Rules

• Use grpc-kotlin coroutine stubs for Kotlin projects — avoid blocking stubs
• Keep proto-to-domain mapping in dedicated mapper files, not inside service implementations
• Use Flow for streaming responses in Kotlin — it integrates naturally with coroutines
• For Java projects, use ListenableFuture stubs or StreamObserver — avoid mixing blocking and async
• Never expose proto-generated classes in your domain layer — always map to domain models
• Use buf or protoc plugins for consistent code generation across projects

9. Spring Boot Integration (grpc-spring)

See references/spring-boot-integration.md for detailed server/client configuration, interceptor setup, and testing patterns.

Quick Start

// build.gradle.kts
dependencies {
    implementation("net.devh:grpc-spring-boot-starter:3.1.0.RELEASE")
    implementation("io.grpc:grpc-kotlin-stub:1.4.1")
    implementation("io.grpc:grpc-protobuf:1.62.2")
    implementation("com.google.protobuf:protobuf-kotlin:3.25.3")
}

Server Configuration

@GrpcService
class OrderGrpcService(
    private val orderService: OrderService
) : OrderServiceGrpcKt.OrderServiceCoroutineImplBase() {

    override suspend fun createOrder(request: CreateOrderRequest): CreateOrderResponse {
        val order = orderService.create(request.toCommand())
        return order.toCreateResponse()
    }

    override suspend fun getOrder(request: GetOrderRequest): Order {
        val order = orderService.findById(request.orderId)
            ?: throw Status.NOT_FOUND
                .withDescription("Order not found: ${request.orderId}")
                .asRuntimeException()
        return order.toProto()
    }
}

# application.yml
grpc:
  server:
    port: 50051
    security:
      enabled: true
      certificate-chain: classpath:certs/server.crt
      private-key: classpath:certs/server.key

Client Configuration

@Configuration
class GrpcClientConfig {

    @GrpcClient("order-service")
    lateinit var orderServiceStub: OrderServiceGrpcKt.OrderServiceCoroutineStub
}

# application.yml
grpc:
  client:
    order-service:
      address: dns:///order-service:50051
      negotiation-type: tls
      enable-keep-alive: true
      keep-alive-time: 30s
      keep-alive-timeout: 5s

Spring Integration Rules

• Use @GrpcService annotation for server-side service beans — it registers them with the gRPC server
• Use @GrpcClient for injecting client stubs — it manages channel lifecycle and load balancing
• Configure TLS in production — never use plaintext in production environments
• Use Spring's @Transactional carefully — gRPC calls are not part of Spring transactions
• Register interceptors as Spring beans with @GrpcGlobalServerInterceptor or @GrpcGlobalClientInterceptor
• Test gRPC services with @GrpcSpringBootTest and grpc-spring-boot-starter-test

10. Service Mesh Integration (Istio / Envoy)

See references/service-mesh-integration.md for detailed Istio/Envoy configuration examples, DestinationRule/VirtualService YAML, and gRPC health check implementation.

Key Benefits

Service Mesh Integration Rules

• Use h2UpgradePolicy: UPGRADE in DestinationRule to ensure HTTP/2 for gRPC traffic
• Delegate mTLS, retries, and circuit breaking to the mesh when available — avoid duplicating in application code
• When using mesh-level retries, disable application-level retries to prevent retry amplification
• Configure outlierDetection for automatic ejection of unhealthy endpoints
• Use Istio VirtualService for canary deployments, traffic splitting, and fault injection
• Ensure gRPC health checking is configured — Envoy uses it for endpoint health status
• Use grpc_health_v1.Health service for standardized health checks

11. Related Skills

Further Reading

• gRPC Official Documentation — Core concepts, guides, and API reference
• Protocol Buffers Language Guide (proto3) — Proto3 syntax and features
• Google API Design Guide — API design patterns applicable to gRPC
• gRPC-Kotlin Documentation — Kotlin-specific gRPC usage
• grpc-spring (grpc-ecosystem) — Spring Boot integration for gRPC
• Envoy gRPC Support — Envoy proxy gRPC features
• Istio Traffic Management — Service mesh traffic policies