gRPC Standards
grpc-standards
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.
SKILL.md
Full skill instructions
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
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 |