gRPC Standards

RFC-33 compliant gRPC service standards for Java services.

When to use this skill

• Creating new gRPC services or clients
• Implementing protobuf contracts
• Adding resilience patterns (retry, bulkhead, circuit breaker)
• Configuring deadline propagation
• Setting up protobuf linting with Buf
• Implementing gRPC error handling

Skill Contents

Sections

• When to use this skill (L24-L32)
• Quick Start (L54-L97)
• Service Implementation (L98-L120)
• Client Configuration (L121-L146)
• References (L147-L154)
• Related Rules (L155-L159)
• Related Skills (L160-L165)

Available Resources

📚 references/ - Detailed documentation

• contracts
• linting
• resilience

---

Quick Start

1. Add Dependencies

# gradle/libs.versions.toml
[versions]
grpc = "1.78.0"
protobuf = "4.33.0"

[libraries]
grpc-protobuf = { module = "io.grpc:grpc-protobuf", version.ref = "grpc" }
grpc-stub = { module = "io.grpc:grpc-stub", version.ref = "grpc" }
grpc-api = { module = "io.grpc:grpc-api", version.ref = "grpc" }
protobuf-java = { module = "com.google.protobuf:protobuf-java", version.ref = "protobuf" }
grpc-resilience-starter = { module = "com.bitso.commons:grpc-resilience-starter", version = "LATEST" }

[plugins]
protobuf = { id = "com.google.protobuf", version = "0.9.6" }

2. Configure gRPC Server

# application.yml
grpc:
  server:
    port: 8201

3. Implement Service Handler

@GrpcService
public class MyServiceHandler extends MyServiceGrpc.MyServiceImplBase {
    @Override
    public void myMethod(MyRequest request, StreamObserver<MyResponse> responseObserver) {
        // Implementation
        responseObserver.onNext(response);
        responseObserver.onCompleted();
    }
}

Service Implementation

Error Handling

Use FailureHelper to send errors in metadata:

public static StatusRuntimeException createStatusRuntimeException(
        Status.Code code, DataCommonsProto.Failure failure) {
    Metadata metadata = new Metadata();
    metadata.put(FAILURE_DETAILS_KEY, failure);
    return code.toStatus().withDescription(failure.getCode()).asRuntimeException(metadata);
}

gRPC Error Codes

Code	Usage
INTERNAL	Infrastructure errors
UNKNOWN	Only used by gRPC core
FAILED_PRECONDITION	Business errors

Client Configuration

With Resilience

grpc:
  client:
    my-service:
      address: dns:/${MY_SERVICE_HOST:localhost}:${GRPC_PORT:8201}
      negotiation-type: PLAINTEXT
      service-config:
        method-config:
          - name: []
            timeout: PT5S
            retry-policy:
              max-attempts: 3
              initial-backoff: PT1S
              max-backoff: PT5S
              backoff-multiplier: 1.5
              retryable-status-codes:
                - UNAVAILABLE
      bulkhead:
        max-concurrent-calls: 10
        max-wait-duration: PT1S

References

Reference	Description
references/contracts.md	Protobuf contract guidelines, versioning, documentation
references/resilience.md	Deadline propagation, retry, bulkhead, circuit breaker
references/linting.md	Buf linting setup and custom rules

Related Rules

• .cursor/rules/java-grpc-services.mdc - gRPC service standards
• .cursor/rules/java-grpc-resilience.mdc - Resilience configuration

Related Skills

Skill	Purpose
gradle-standards	Dependency configuration
java-testing	Testing gRPC services