gRPC Playbook (Java)

Scope

In scope

• .proto conventions (packages, naming, versioning, reserved fields).
• API surface: unary vs streaming; pagination patterns; metadata.
• Reliability: deadlines/timeouts, cancellation, retry policy design.
• Error model: mapping domain errors to gRPC status codes + details.
• Streaming guidelines: flow control, message size, backpressure, ordering.
• Client/server skeletons and testing approaches.

Out of scope

• Service mesh specifics and advanced LB policy tuning unless requested.

When to use

• You are introducing internal RPC between services.
• You need performance and strict contracts.
• You are refactoring REST internals to gRPC or diagnosing timeout/retry storms.

Inputs (required context)

• Service boundaries and critical paths (p99 latency expectations).
• Backward compatibility requirement (multi-version clients).
• Idempotency of methods (safe for retries?).
• Streaming needs and expected message sizes.
• AuthN/AuthZ mechanism (mTLS, tokens, metadata).

Proto design rules (compatibility-first)

• Use proto3.
• Never change numeric field tags; never reuse removed tags—use reserved.
• Prefer additive changes: add optional fields; keep old fields until all clients migrate.
• Versioning strategy:

- Prefer versioned packages: com.company.foo.v1 - Or version service names: FooServiceV1 only if packages can’t change.

Error model (status mapping)

• Use standard gRPC status codes:

- INVALIDARGUMENT for validation failures - NOTFOUND for missing resources - ALREADYEXISTS for conflicts - PERMISSIONDENIED / UNAUTHENTICATED for auth - FAILED_PRECONDITION for state conflicts - UNAVAILABLE for transient upstream issues - INTERNAL for unexpected errors

• Include structured error details when needed (e.g., field violations).

Deadlines, timeouts, and cancellation (mandatory discipline)

• Clients must set per-RPC deadlines based on SLO.
• Servers should propagate cancellation to downstream calls.
• Avoid “infinite” deadlines; they cause resource leaks and queueing collapse.

Retries (be explicit)

• Retrying non-idempotent methods can create duplicates.
• Only enable retries for idempotent methods or when protected by idempotency keys.
• Use gRPC retry policies via service config (where supported) with maxAttempts, backoff, and retryableStatusCodes.

Streaming guidelines

• Choose streaming only when it materially improves:

- large payload chunking - server push updates - high-frequency telemetry

• Apply backpressure:

- server must not outpace client’s ability to receive - handle flow control events

• Cap message sizes; consider chunking for large blobs.
• Define ordering guarantees: per stream vs global.

Procedure (step-by-step)

Step 1 — Create Proto Contract

Create proto/<service>/v1/<service>.proto:

• package + javapackage + javamultiple_files
• service definition
• request/response messages
• comments for semantics, idempotency, and error mapping

Step 2 — Generate stubs and implement server

• Implement server handlers.
• Add interceptors for:

- correlation IDs - auth context extraction - metrics and tracing

• Ensure exceptions map to StatusRuntimeException with proper status codes.

Step 3 — Implement client with deadlines and safe retries

• Use shared Channel management (singleton per destination).
• Always set deadlines on stubs.
• For retryable calls: define service config policy; ensure idempotency.

Step 4 — Add compatibility guardrails

• Add CI checks to prevent breaking proto changes:

- enforce reserved tags for removed fields - forbid renumbering

• Document deprecation windows.

Step 5 — Testing

• Unit tests: in-process server + stub calls.
• Integration tests: spin real server (or container) and validate deadlines and error mapping.

Output / Artifacts

• proto/.../*.proto
• src/main/java/.../grpc/server/ implementation
• src/main/java/.../grpc/client/ client wrapper with deadlines
• src/test/java/.../grpc/ tests (in-process)
• docs/rpc/<service>.md (contract + SLA + retry policy)

Definition of Done (DoD)

• Proto contract exists with compatibility rules and comments.
• Deadlines are enforced by clients and propagated.
• Error mapping is standardized and tested.
• Retry policy is explicit and only for idempotent operations (or guarded).
• Streaming endpoints include backpressure and size caps.
• Tests cover: deadline exceeded, cancelled, invalid argument, unavailable.

Guardrails (What NOT to do)

• Never ship client calls without deadlines.
• Never enable retries globally without idempotency analysis.
• Never reuse proto field tags; always reserve.
• Avoid streaming for simple request/response; keep APIs simple.

Skeletons

Proto template

syntax = "proto3";

package com.company.foo.v1;

option java_multiple_files = true;
option java_package = "com.company.foo.v1";

service FooService {
  // Idempotency: YES (safe to retry) if request.idempotency_key is stable
  rpc GetFoo(GetFooRequest) returns (GetFooResponse);
}

message GetFooRequest {
  string foo_id = 1;
}

message GetFooResponse {
  Foo foo = 1;
}

message Foo {
  string id = 1;
  string name = 2;
  // reserved 3; // if removed later
}

Client deadline snippet (grpc-java)

FooServiceGrpc.FooServiceBlockingStub stub = FooServiceGrpc.newBlockingStub(channel)
  .withDeadlineAfter(200, TimeUnit.MILLISECONDS);

GetFooResponse resp = stub.getFoo(GetFooRequest.newBuilder().setFooId(id).build());

Error mapping snippet

throw Status.INVALID_ARGUMENT
  .withDescription("foo_id must be non-empty")
  .asRuntimeException();

Common failure modes & fixes

• Symptom: tail latency spikes → Cause: missing deadlines + queueing → Fix: set deadlines, propagate cancellation.

• Symptom: duplicate side effects → Cause: retries on non-idempotent RPC → Fix: disable retries or add idempotency keys.

• Symptom: clients break after proto change → Cause: field renumber/reuse → Fix: reserved tags, additive evolution.

References

• Use official gRPC docs for deadlines, status codes, keepalive, retries, and streaming concepts.
• Use official Protobuf guidance for field compatibility and reserved tags.