grpc-services-rfc-33

name: grpc-services-rfc-33 description: > RFC-33 compliant gRPC service standards for Java services. Covers protobuf contracts, service implementation, resilience patterns (retry, bulkhead, circuit breaker), and linting. Use when creating or maintaining gRPC services and clients. compatibility: Java projects using gRPC with Spring Boot; requires Buf CLI and bitso-grpc-linter metadata: version: "1.0.0" technology: java category: infrastructure tags: - java - grpc - rfc-33 - protobuf - resilience

gRPC Services (RFC-33)

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
• Prerequisites
• Quick Start
• Service Implementation
• Client Configuration
• References
• Related Rules
• Related Skills

Available Resources

references/ - Detailed documentation

• contracts
• installation
• linting
• resilience

Prerequisites

Buf CLI and the Bitso gRPC Linter must be installed for protobuf linting and compliance validation.

Cloud agents: Pre-installed (no action needed).

Local setup:

export HOMEBREW_GITHUB_API_TOKEN=your-token
brew tap bitsoex/homebrew-bitso
brew install bitso-grpc-linter
brew install bufbuild/buf/buf

Verify: buf --version and grpc-compliance-validate-repository --help

See references/installation.md for details, Docker alternative, and troubleshooting.

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

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

Related Rules

• java-grpc-services - gRPC service standards
• java-grpc-resilience - Resilience configuration

Related Skills