grpc-standards

• 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

Sections

• [When to use this skill](#when-to-use-this-skill) (L24-L32)
• [Quick Start](#quick-start) (L54-L97)
• [Service Implementation](#service-implementation) (L98-L120)
• [Client Configuration](#client-configuration) (L121-L146)
• [References](#references) (L147-L154)
• [Related Rules](#related-rules) (L155-L159)
• [Related Skills](#related-skills) (L160-L165)

Available Resources

📚 references/ - Detailed documentation

• [contracts](references/contracts.md)
• [linting](references/linting.md)
• [resilience](references/resilience.md)

---

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 responseObserver) {

// Implementation

responseObserver.onNext(response);

responseObserver.onCompleted();

}

}

```

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 |

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

```

| Reference | Description |

|-----------|-------------|

| [references/contracts.md](references/contracts.md) | Protobuf contract guidelines, versioning, documentation |

| [references/resilience.md](references/resilience.md) | Deadline propagation, retry, bulkhead, circuit breaker |

| [references/linting.md](references/linting.md) | Buf linting setup and custom rules |

• .cursor/rules/java-grpc-services.mdc - gRPC service standards
• .cursor/rules/java-grpc-resilience.mdc - Resilience configuration

| Skill | Purpose |

|-------|---------|

| [gradle-standards](../gradle-standards/SKILL.md) | Dependency configuration |

| [java-testing](../java-testing/SKILL.md) | Testing gRPC services |