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

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/installation.md	Buf CLI and gRPC Linter installation (Homebrew, Docker, cloud)
references/linting.md	Buf linting setup and custom rules
references/resilience.md	Deadline propagation, retry, bulkhead, circuit breaker

Related Rules

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

Related Skills

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