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