gRPC Services (RFC-33) Skill

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

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

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

Agent Skills: gRPC Services (RFC-33)

Install this agent skill to your local

Skill Files