klod68/grpc-standards

---

name: grpc-standards description: "Use when working with gRPC services, protobuf definitions, Protocol Buffers, streaming RPCs, interceptors, or gRPC client configuration in .NET. Provides domain-specific rules layered on top of base architectural standards."

Skill: gRPC Service Standards

Identity

| Field | Value | |---|---| | Name | gRPC Service Standards | | Domain | API, Messaging, RPC | | Level | Feature | | Tags | grpc, protobuf, streaming, interceptors, rpc |

When to Apply

Activate this skill when the task involves:

• Defining or editing .proto files
• Implementing gRPC service classes
• Server or client streaming patterns
• gRPC interceptors (logging, auth, error mapping)
• Deadline and timeout configuration
• gRPC client registration and channel management

Rules

These rules layer on top of base architectural standards. On conflict, these win.

<!-- SHARED:rules/grpc.md -->

gRPC — Service Standards

Apply these rules in addition to _base.md for projects using gRPC services.

---

Protobuf Conventions

• One .proto file per service — file name matches service name: order_service.proto.
• Use snake_case for field names, PascalCase for message and service names (protobuf convention).
• Set option csharp_namespace explicitly to control generated C# namespace.
• Version APIs via package name: package myapp.orders.v1; — never reuse package names for breaking changes.
• Every RPC method has a dedicated Request and Response message — never reuse messages across RPCs.
• Use google.protobuf.Timestamp for dates, google.protobuf.Duration for time spans, google.protobuf.StringValue for nullable strings.

Service Implementation

• Inherit from generated Base class: public class OrderService : Orders.OrdersBase.
• Keep service methods thin — delegate to Application layer handlers (same as Minimal API handlers).
• Inject dependencies via constructor DI — gRPC services are registered as scoped by default.
• Always accept ServerCallContext and propagate its CancellationToken to downstream calls.
• Return domain errors via RpcException with appropriate StatusCode — never throw raw exceptions.

Streaming Patterns

• Server streaming: use async + yield return pattern or write to IServerStreamWriter<T> in a loop.
• Client streaming: read from IAsyncStreamReader<T> until MoveNext() returns false.
• Bidirectional: use Task.WhenAll to read and write concurrently, not sequentially.
• Always check context.CancellationToken in streaming loops — abort cleanly on client disconnect.
• Set reasonable MaxReceiveMessageSize and MaxSendMessageSize (default 4MB is often too small for file transfers).

Deadlines & Timeouts

• Every client call must set a deadline: client.GetOrderAsync(req, deadline: DateTime.UtcNow.AddSeconds(5)).
• Propagate incoming deadlines to downstream calls — use context.Deadline for cascading timeouts.
• Handle StatusCode.DeadlineExceeded explicitly in client error handling.
• Set global channel options for default deadline: GrpcChannelOptions.MaxReceiveMessageSize.

Error Handling

• Map domain errors to gRPC status codes:

| Domain Error | gRPC StatusCode | When | |---|---|---| | Not found | NotFound | Resource doesn't exist | | Validation failure | InvalidArgument | Bad request data | | Already exists | AlreadyExists | Duplicate create | | Permission denied | PermissionDenied | Auth check failed | | Unauthorized | Unauthenticated | No/invalid credentials | | Business rule violation | FailedPrecondition | State doesn't allow operation | | Timeout | DeadlineExceeded | Operation took too long | | Internal error | Internal | Unexpected server error |

• Include detail metadata in RpcException for debugging — never expose stack traces.
• Use interceptors for global error mapping — don't repeat try/catch in every RPC method.

Interceptors

• Use server interceptors for cross-cutting concerns: logging, metrics, auth, error mapping.
• One concern per interceptor — same single-responsibility as middleware.
• Register interceptors in AddGrpc(options => options.Interceptors.Add<LoggingInterceptor>()).
• Client interceptors for: retry, deadline propagation, auth token injection.

Client Configuration

• Use GrpcChannel.ForAddress with IHttpClientFactory for connection management.
• Register typed clients via AddGrpcClient<OrderService.OrderServiceClient>() in DI.
• Enable retry via ServiceConfig — gRPC has built-in retry policy support.
• Use CallInvoker for testing — mock at the channel level, not the service level.

Common Anti-Patterns

| Anti-Pattern | Fix | |---|---| | No deadline on client calls | Always set deadline: parameter | | Throwing Exception from service method | Return RpcException(new Status(StatusCode.X, "msg")) | | Large messages without streaming | Use server streaming for collections > 100 items | | Blocking in streaming loop | Use async/await with CancellationToken | | Reusing request/response messages across RPCs | One dedicated message pair per RPC method | | new GrpcChannel() per call | Use DI with AddGrpcClient<T>() | | Missing option csharp_namespace in .proto | Generates messy namespace — always specify | | Sequential read/write in bidirectional stream | Use Task.WhenAll for concurrent read and write |

---

See Also

• api-design.md — RESTful conventions, HTTP methods, pagination, error responses
• resilience.md — Polly v8 resilience pipelines, retry, circuit breaker, timeout
• auth.md — Authentication, authorization, OAuth/OIDC, secrets management
• result-error-handling.md — Result object pattern, error constants, exception boundaries