Nyxalon.Resilience 1.0.0-beta.145

Nyxalon.Resilience

A thin, opinionated resilience pipeline abstraction built on top of Polly, wired via Microsoft.Extensions.DependencyInjection.

Provides retry and circuit breaker policies behind a clean IResiliencePipeline interface — no Polly internals leaking into your application code.

Installation

dotnet add package Nyxalon.Resilience

Getting Started

Register pipelines in your Program.cs (or Startup.cs):

builder.Services.AddResilienceKit(options =>
{
    options.AddPipeline("default", builder =>
    {
        builder
            .AddRetry(new RetryOptions
            {
                RetryCount = 3,
                BaseDelayMilliseconds = 200
            })
            .AddCircuitBreaker(new CircuitBreakerOptions
            {
                FailureThreshold = 0.5,
                SamplingDurationSeconds = 30,
                MinimumThroughput = 10,
                BreakDurationSeconds = 60
            });
    });
});

Inject and use IResiliencePipelineProvider anywhere in your app:

public class OrderService(IResiliencePipelineProvider pipelines)
{
    public async Task PlaceOrderAsync(Order order, CancellationToken ct)
    {
        IResiliencePipeline pipeline = pipelines.GetPipeline("default");

        await pipeline.ExecuteAsync(async () =>
        {
            await _httpClient.PostAsJsonAsync("/orders", order, ct);
        }, ct);
    }
}

Policies

Retry

Retries a failed operation with linear back-off.

builder.AddRetry(new RetryOptions
{
    RetryCount = 3,           // number of retry attempts
    BaseDelayMilliseconds = 200  // delay = BaseDelay * attemptNumber
});

With the defaults, delays will be: 200ms → 400ms → 600ms.

Circuit Breaker

Opens the circuit when the failure rate exceeds the threshold, blocking calls for the break duration.

builder.AddCircuitBreaker(new CircuitBreakerOptions
{
    FailureThreshold = 0.5,        // 50% failure rate opens the circuit
    SamplingDurationSeconds = 30,  // measured over a 30s window
    MinimumThroughput = 10,        // at least 10 calls needed before measuring
    BreakDurationSeconds = 60      // circuit stays open for 60s
});

When the circuit is open, calls throw BrokenCircuitException immediately without reaching the underlying operation.

Combining Policies

Policies are applied in the order they are added — outermost first. The recommended order is retry wrapping circuit breaker:

options.AddPipeline("external-api", builder =>
{
    builder
        .AddRetry(new RetryOptions { RetryCount = 2, BaseDelayMilliseconds = 100 })
        .AddCircuitBreaker(new CircuitBreakerOptions { MinimumThroughput = 5 });
});

This means: retry up to 2 times, but if the circuit is already open, fail immediately without retrying.

Multiple Named Pipelines

Register as many pipelines as you need — each with its own policy configuration:

builder.Services.AddResilienceKit(options =>
{
    // Aggressive retry for internal services
    options.AddPipeline("internal", builder =>
    {
        builder.AddRetry(new RetryOptions { RetryCount = 5, BaseDelayMilliseconds = 50 });
    });

    // Conservative for third-party APIs
    options.AddPipeline("external", builder =>
    {
        builder
            .AddRetry(new RetryOptions { RetryCount = 2, BaseDelayMilliseconds = 500 })
            .AddCircuitBreaker(new CircuitBreakerOptions
            {
                FailureThreshold = 0.3,
                BreakDurationSeconds = 120
            });
    });

    // No-op pipeline for local/dev
    options.AddPipeline("noop", _ => { });
});

Return Values

ExecuteAsync has a generic overload for operations that return a value:

IResiliencePipeline pipeline = pipelines.GetPipeline("external");

Product? product = await pipeline.ExecuteAsync(async () =>
{
    return await _httpClient.GetFromJsonAsync<Product>($"/products/{id}");
});

License

MIT © Nyxalon