backend-grpc-patterns

Backend gRPC Patterns

Purpose

Design consistent, production-grade gRPC services. Every RPC must follow the same conventions for protobuf schemas, streaming patterns, interceptors, error handling, and service versioning.

Agent Protocol

Trigger

Exact user phrases: "gRPC", "protobuf", "protocol buffers", "streaming RPC", "unary call", "server streaming", "client streaming", "bidirectional streaming", "gRPC interceptor", "gRPC error handling", "protobuf schema", "service definition", "design an RPC", "gRPC contract".

Input Context

Before activating, verify:

• The service or feature being designed is known.
• The proto package name and version are known.
• The streaming model (unary/server-stream/client-stream/bidi) is chosen. If not, ask: "What streaming model do you need?"
• The language/runtime for code generation is known.

Output Artifact

No file output unless the user requests it. Produces protobuf schema and RPC specifications as text.

Response Format

For each RPC:

rpc {MethodName}({RequestType}) returns ({ResponseType})
Streaming: {none/server/client/bidirectional}
Auth: {required/optional/none}
Deadline: {timeout suggestion}
Errors: {list of gRPC status codes}

For a full service definition:

service {ServiceName} {
  {list of RPCs}
}

No preamble. No postamble. No explanations. No filler/hedging/transitions. Compress output — why use many token when few do trick.

Completion Criteria

• All protobuf packages follow the naming conventions below.
• Every RPC has: method signature, streaming type, auth requirement, deadline, error codes.
• Protobuf messages are versioned in the package name.
• Error responses use standard gRPC status codes with rich detail.
• All streaming RPCs include proper backpressure handling.
• Interceptor chain is documented.

Max Response Length

Per RPC: 6 lines. Per service: unlimited.

Decision Tree

Which RPC Pattern?

What is the communication pattern?
  ├── Request → Response (standard CRUD)
  │   └── Unary RPC — simplest, HTTP/2 under the hood
  ├── Request → stream of events (subscribe, watch, notifications)
  │   └── Server-streaming RPC — send multiple responses for one request
  ├── Stream of requests → single response (batch upload, long-form input)
  │   └── Client-streaming RPC — aggregate client data into one result
  ├── Stream → stream (chat, real-time sync, gaming)
  │   └── Bidirectional streaming — full-duplex communication
  └── Fire-and-forget (event, notification, pub/sub)
      └── Consider message queue instead — gRPC streaming is for persistent connections