grpc-patterns

name	grpc-patterns
description	gRPC communication patterns for ASP.NET Core — unary, server streaming, client streaming, and bidirectional streaming. Use when implementing or choosing between RPC patterns.

gRPC Communication Patterns

1. Unary RPC

One request, one response. The simplest and most common pattern.

Proto definition:

rpc GetUser (GetUserRequest) returns (GetUserResponse);

Server implementation:

public override Task<GetUserResponse> GetUser(
    GetUserRequest request, ServerCallContext context)
{
    // Propagate cancellation
    context.CancellationToken.ThrowIfCancellationRequested();
    // Return single response
    return Task.FromResult(new GetUserResponse { /* ... */ });
}

When to use: CRUD operations, simple queries, authentication, validation.

---

2. Server Streaming RPC

One request, stream of responses from the server.

Proto definition:

rpc ListUsers (ListUsersRequest) returns (stream UserResponse);

Server implementation:

public override async Task ListUsers(
    ListUsersRequest request,
    IServerStreamWriter<UserResponse> responseStream,
    ServerCallContext context)
{
    await foreach (var user in GetUsersAsync(context.CancellationToken))
    {
        await responseStream.WriteAsync(user, context.CancellationToken);
    }
}

Client consumption:

using var call = client.ListUsers(new ListUsersRequest());
await foreach (var user in call.ResponseStream.ReadAllAsync(ct))
{
    // Process each user
}

When to use: Large result sets, real-time feeds, notifications, log streaming.

---

3. Client Streaming RPC

Stream of requests from the client, one response from the server.

Proto definition:

rpc UploadData (stream DataChunk) returns (UploadResult);

Server implementation:

public override async Task<UploadResult> UploadData(
    IAsyncStreamReader<DataChunk> requestStream,
    ServerCallContext context)
{
    long totalBytes = 0;
    await foreach (var chunk in requestStream.ReadAllAsync(context.CancellationToken))
    {
        totalBytes += chunk.Data.Length;
        // Process chunk
    }
    return new UploadResult { BytesReceived = totalBytes };
}

Client usage:

using var call = client.UploadData();
foreach (var chunk in dataChunks)
{
    await call.RequestStream.WriteAsync(chunk);
}
await call.RequestStream.CompleteAsync(); // IMPORTANT: signal completion
var result = await call;

When to use: File uploads, batch operations, telemetry ingestion, aggregation.

---

4. Bidirectional Streaming RPC

Both client and server stream simultaneously.

Proto definition:

rpc Chat (stream ChatMessage) returns (stream ChatMessage);

Server implementation:

public override async Task Chat(
    IAsyncStreamReader<ChatMessage> requestStream,
    IServerStreamWriter<ChatMessage> responseStream,
    ServerCallContext context)
{
    await foreach (var message in requestStream.ReadAllAsync(context.CancellationToken))
    {
        var reply = new ChatMessage { Text = $"Echo: {message.Text}" };
        await responseStream.WriteAsync(reply, context.CancellationToken);
    }
}

Client usage:

using var call = client.Chat();
// Send and receive concurrently
var readTask = Task.Run(async () =>
{
    await foreach (var msg in call.ResponseStream.ReadAllAsync(ct))
    {
        Console.WriteLine(msg.Text);
    }
});

foreach (var msg in messages)
{
    await call.RequestStream.WriteAsync(msg);
}
await call.RequestStream.CompleteAsync();
await readTask;

When to use: Real-time chat, collaborative editing, game state sync, reactive pipelines.

---

Pattern Selection Guide

Criterion	Unary	Server Stream	Client Stream	Bidi Stream
Simple request/response	YES	-	-	-
Large result set	-	YES	-	-
File upload	-	-	YES	-
Real-time bidirectional	-	-	-	YES
Easy to load balance	YES	YES	YES	NO
Easy to debug	YES	MODERATE	MODERATE	DIFFICULT

Key Rules

• Always dispose streaming calls with using
• Always call CompleteAsync() on request streams when done
• Always read response streams to completion for graceful shutdown
• Prefer unary RPCs unless streaming provides measurable benefit
• Streaming RPCs cannot be load-balanced once started