Agent skill

grpc-services-rfc-33

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.

Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/grpc-services-rfc-33

Metadata

Additional technical details for this skill

tags
java grpc rfc-33 protobuf resilience
version
1.0.0
category
infrastructure
technology
java

SKILL.md

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


Quick Start

1. Add Dependencies

toml
# 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

yaml
# application.yml
grpc:
  server:
    port: 8201

3. Implement Service Handler

java
@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:

java
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

yaml
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

Related Skills

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

Didn't find tool you were looking for?

Be as detailed as possible for better results