stevenacoffman/grpc
gRPC service design, testing, deployment, and load balancing.
Trigger when setting up unit tests for a gRPC service that need a real gRPC server without binding a network port, or when needing per-test fault injection on storage doubles.
Invoke when choosing between gRPC's four communication patterns (unary, server streaming, client streaming, bidirectional streaming) for a new service method. Trigger conditions: designing a new RPC that involves multiple results, batched writes, or real-time full-duplex flows.
Trigger when running a gRPC server and a Prometheus metrics HTTP server in the same process with unified error propagation and coordinated graceful shutdown.
Trigger when implementing caller-controlled partial field selection on a gRPC read or list endpoint, especially streaming, to prevent over-fetching.
Trigger when designing or optimizing a client-streaming RPC request message that currently wraps a domain object in a nested sub-message.
Trigger when deploying a gRPC microservice to Kubernetes and need the correct combination of resources for external access, TLS termination, and inter-service communication.
Invoke when gRPC traffic is unevenly distributed across backend pods, or when reviewing a gRPC deployment behind a TCP/L4 load balancer. L4 balancers distribute connections, not RPCs, and HTTP/2 multiplexing sends every RPC on a connection to one backend.
Invoke when choosing a load balancing strategy for gRPC services, or when one backend gets all the traffic. Generic L4 TCP load balancers do not spread gRPC traffic; use an L7 proxy with explicit gRPC support or client-side load balancing.
Invoke when a team proposes exposing a gRPC service directly to third-party consumers, public API users, or browser clients. Recommends gRPC internally with HTTP/JSON transcoding (grpc-gateway or Envoy) at the boundary instead of direct exposure.
Trigger when optimizing Protobuf message sizes or deciding whether to enable gzip compression on a gRPC service.
Trigger when designing distributed transaction rollback across multiple microservices, or when choosing between choreography-based and orchestrator-based saga implementations.
Invoke when securing a gRPC service or client in production, including OAuth2 or JWT with gRPC. Two independent layers must both be configured: channel credentials (TLS or mTLS) for transport and per-RPC call credentials (OAuth2 or JWT).
Trigger when deciding how to decompose a monolith into gRPC microservices, or when evaluating the boundaries between services in a microservice system.
Invoke when structuring tests for a gRPC service with interceptors (auth, rate limit, TLS) and infrastructure dependencies, or when unit tests pass but integration is flaky. Keeps interceptor-chain tests (real TLS over bufconn) separate from adapter tests (testcontainers, wait.ForSQL).
Invoke when an architecture decision must choose between gRPC, REST/HTTP-JSON, or GraphQL for a service interface, including whether to expose gRPC to external consumers. Weighs internal vs external, synchronous vs event-driven, and field-selection needs.