Grpc

---
name: grpc
description: "gRPC 1.x covering Protocol Buffers, service definitions, streaming patterns, channels, interceptors, metadata, deadlines, error model, load balancing, health checking, retry policies, and performance tuning. Use for \"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\"."
license: MIT
---

# gRPC 1.x

This skill covers gRPC, the high-performance RPC framework built on HTTP/2 and Protocol Buffers. gRPC 1.x is the current stable major version. It has 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** -- Read the `overview` skill

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

- `overview` skill -- cross-protocol comparisons
- `rest` skill -- 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