| 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
Available Resources
references/ - Detailed documentation
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
[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
grpc:
server:
port: 8201
3. Implement Service Handler
@GrpcService
public class MyServiceHandler extends MyServiceGrpc.MyServiceImplBase {
@Override
public void myMethod(MyRequest request, StreamObserver<MyResponse> responseObserver) {
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
Related Rules
Related Skills
