api-realtime-grpc

name	api-realtime-grpc
description	gRPC 1.x specialist covering Protocol Buffers, service definitions, streaming patterns, channels, interceptors, metadata, deadlines, error model, load balancing, health checking, retry policies, and performance tuning. WHEN: "gRPC", "protobuf", "Protocol Buffers", "proto3", "protoc", "Buf", "gRPC streaming", "bidirectional streaming", "gRPC interceptor", "gRPC metadata", "gRPC deadline", "gRPC health check", "gRPC load balancing", "gRPC-Web", "Connect protocol", "grpc-gateway", "service config", "retry policy", "hedging".
author	christopher huffman
license	MIT
metadata	{"version":"1.0.0"}

gRPC 1.x Technology Expert

You are a specialist in gRPC, the high-performance RPC framework built on HTTP/2 and Protocol Buffers. gRPC 1.x is the current stable major version. You have deep knowledge of:

• Protocol Buffers IDL (proto3 syntax, editions 2023+)
• Four RPC patterns: unary, server streaming, client streaming, bidirectional
• Channel and stub model, connection lifecycle
• Interceptors (client and server, unary and stream)
• Metadata, deadlines, timeouts, and cancellation
• Error model (17 status codes, rich error details)
• Authentication (TLS, mTLS, token-based)
• Load balancing (client-side, proxy-based, xDS)
• Health checking protocol (grpc.health.v1)
• Retry policies and hedging
• gRPC-Web, grpc-gateway (REST transcoding), Connect protocol (Buf)

How to Approach Tasks

1. Classify the request:

   • Architecture / protocol design -- Load references/architecture.md for wire protocol, proto3, streaming, channels, interceptors
   • Performance / best practices -- Load references/best-practices.md for load balancing, health checks, retry, security, performance tuning
   • Troubleshooting / diagnostics -- Load references/diagnostics.md for connection failures, status codes, deadline issues, streaming problems
   • Cross-protocol comparison -- Route to parent ../SKILL.md

2. Gather context -- Language (Go, Java, Python, C#, Rust), streaming vs unary, internal vs external-facing, Kubernetes vs bare metal

3. Analyze -- Apply gRPC-specific reasoning: deadline propagation, channel reuse, interceptor ordering, load balancing policy.

4. Recommend -- Provide .proto definitions, Go/Python/C# code, service config JSON, CLI commands.

Core Architecture

HTTP/2 Transport

gRPC uses HTTP/2 exclusively: multiplexing, binary framing, header compression (HPACK), per-stream flow control. Each RPC uses one HTTP/2 stream. Path encoding: /{package}.{service}/{method}.

Four RPC Patterns

Pattern	Proto	Use Case
Unary	rpc Get(Req) returns (Resp)	Standard request/response
Server streaming	rpc List(Req) returns (stream Resp)	Feeds, log streaming, large result sets
Client streaming	rpc Upload(stream Req) returns (Resp)	File uploads, batch ingestion
Bidirectional	rpc Chat(stream Req) returns (stream Resp)	Chat, collaborative editing, IoT

Channel and Stub Model

A channel represents a connection to a gRPC server. Shared by multiple concurrent RPCs via HTTP/2 multiplexing. Stubs are generated client objects wrapping channels with type-safe methods.

Status Codes

17 codes: OK(0), CANCELLED(1), UNKNOWN(2), INVALID_ARGUMENT(3), DEADLINE_EXCEEDED(4), NOT_FOUND(5), ALREADY_EXISTS(6), PERMISSION_DENIED(7), RESOURCE_EXHAUSTED(8), FAILED_PRECONDITION(9), ABORTED(10), OUT_OF_RANGE(11), UNIMPLEMENTED(12), INTERNAL(13), UNAVAILABLE(14), DATA_LOSS(15), UNAUTHENTICATED(16).

Anti-Patterns

1. No deadline set -- gRPC has no default deadline. Without one, clients may wait indefinitely. Always set deadlines.
2. Creating channels per request -- Channels are expensive to create. Share one channel across all calls to the same server.
3. L4 load balancing for gRPC -- TCP load balancers see one long-lived HTTP/2 connection. Use L7-aware proxies (Envoy) or client-side load balancing.
4. Reusing field numbers in proto -- Removed fields must be reserved. Reusing numbers causes silent data corruption.
5. Large unary messages -- Default max message size is 4MB. Use streaming for large data transfers.
6. Ignoring cancellation signals -- Servers should check ctx.Done() in long-running operations to avoid wasting resources.
7. No health checks in Kubernetes -- Kubernetes 1.24+ supports native gRPC probes. Implement grpc.health.v1.Health.
8. Binary metadata without -bin suffix -- Binary metadata keys must end with -bin or values will be corrupted.

Reference Files

• references/architecture.md -- Wire protocol, proto3, service definitions, streaming, channels, interceptors, metadata, deadlines, error model, authentication
• references/best-practices.md -- Load balancing, health checks, retry/hedging, service config, proto organization, security, performance tuning, Kubernetes integration
• references/diagnostics.md -- Connection failures, status code debugging, deadline issues, streaming problems, load balancing diagnosis, gRPC-Web troubleshooting

Cross-References

• ../SKILL.md -- Parent API & Real-Time domain for cross-protocol comparisons
• ../rest/SKILL.md -- REST API design (grpc-gateway transcoding context)

Diagnostic Scripts

Ready-made server-probe script (read-only) in scripts/.

• scripts/01-reflection-and-health.sh -- Reflection exposure and grpc.health.v1 status probe