PollyGrpc 1.0.0

PollyGrpc

Polly v8 resilience for gRPC .NET clients — retry, circuit breaker, and per-call timeout via a lightweight Interceptor, no protobuf changes required.

Why PollyGrpc?

gRPC services can fail transiently (network blips, overloaded servers, rolling restarts). Without resilience, a single Unavailable or ResourceExhausted status crashes your call. PollyGrpc wraps every call in a Polly v8 pipeline so transient failures are retried automatically, persistent failures trip the circuit breaker, and runaway calls are cancelled by a configurable timeout.

Installation

dotnet add package PollyGrpc

Quick Start

With AddGrpcClient<T>() (recommended)

builder.Services
    .AddGrpcClient<Greeter.GreeterClient>(o =>
        o.Address = new Uri("https://my-grpc-service"))
    .AddPollyGrpcResilience(o =>
    {
        o.MaxRetries    = 3;
        o.BaseDelay     = TimeSpan.FromMilliseconds(200);
        o.CallTimeout   = TimeSpan.FromSeconds(10);
    });

With a raw CallInvoker

var channel = GrpcChannel.ForAddress("https://my-grpc-service");
var invoker = channel.CreateCallInvoker()
                     .WithPollyResilience(o => o.MaxRetries = 3);

var client = new Greeter.GreeterClient(invoker);

Configuration

var options = new PollyGrpcOptions
{
    // Retry
    MaxRetries = 3,                              // 0 = no retry
    BaseDelay  = TimeSpan.FromMilliseconds(200), // exponential base
    MaxDelay   = TimeSpan.FromSeconds(30),

    // Circuit breaker
    CircuitBreakerFailureRatio        = 0.5,
    CircuitBreakerMinimumThroughput   = 10,
    CircuitBreakerSamplingDuration    = TimeSpan.FromSeconds(30),
    CircuitBreakerBreakDuration       = TimeSpan.FromSeconds(5),

    // Timeout
    CallTimeout = TimeSpan.FromSeconds(10),

    // Which gRPC status codes are treated as transient (and therefore retried)
    TransientStatusCodes = new HashSet<StatusCode>
    {
        StatusCode.Unavailable,
        StatusCode.DeadlineExceeded,
        StatusCode.ResourceExhausted,
        StatusCode.Aborted,
        StatusCode.Internal,
    },
};

Error Handling

Non-transient RpcExceptions (e.g. NotFound, PermissionDenied) are rethrown as-is. After all retries are exhausted the last exception is a TransientRpcException wrapping the original RpcException:

try
{
    var reply = await client.SayHelloAsync(new HelloRequest { Name = "World" });
}
catch (TransientRpcException ex)
{
    // All retries failed
    Console.WriteLine($"gRPC status: {ex.StatusCode}");
    Console.WriteLine($"Original error: {ex.RpcException.Status.Detail}");
}
catch (BrokenCircuitException)
{
    // Circuit is open — fail fast without calling the server
}
catch (TimeoutRejectedException)
{
    // Call exceeded CallTimeout
}

Resilience Pipeline Order

Calls flow through the pipeline in this order:

Retry → Circuit Breaker → Timeout → gRPC call

Related Packages

License

MIT