ZeroAlloc.Resilience 3.3.0

ZeroAlloc.Resilience

Source-generated, zero-allocation resilience policies for .NET.

Add [Retry], [Timeout], [RateLimit], and [CircuitBreaker] to an interface. A Roslyn source generator emits a proxy class that composes all policies in declaration order with no heap allocation on the happy path (beyond the unavoidable CancellationTokenSource for timeout). AOT-safe.

Quick start

dotnet add package ZeroAlloc.Resilience

[Retry(MaxAttempts = 3, BackoffMs = 200, Jitter = true, PerAttemptTimeoutMs = 1_000)]
[Timeout(Ms = 5_000)]
[RateLimit(MaxPerSecond = 100, BurstSize = 10)]
[CircuitBreaker(MaxFailures = 5, ResetMs = 1_000, HalfOpenProbes = 1, Fallback = nameof(FetchFallback))]
public interface IExternalService
{
    ValueTask<string> FetchAsync(string id, CancellationToken ct);
    ValueTask<string> FetchFallback(string id, CancellationToken ct);
}

// Register — one line wires everything
builder.Services.AddExternalServiceResilience<ExternalServiceImpl>();

Inject IExternalService anywhere — all policies are transparent to the caller.

Performance

Head-to-head vs Polly v8 (the de-facto resilience library in .NET). .NET 10.0.7, BenchmarkDotNet v0.14.0.

The happy-path gap is driven by Polly's ResiliencePipeline.ExecuteAsync walking the strategy chain via delegate dispatch and allocating a ResilienceContext per call (64 B). ZA emits one direct method per interface — retry/CB checks are inline if statements with no context object or closure.

The retry-with-failures wall-clock gap is dominated by Task.Delay(BackoffMs); the residual 22% is ZA's for-loop scheduling — measurable, but mostly invisible against I/O latency.

Full methodology + self-benchmark: docs/performance.md.

Features

Policy execution order

Policies execute in this order on every call:

RateLimit → CircuitBreaker → Timeout → Retry (with PerAttemptTimeout inside)

Each policy runs before the inner call is even attempted. If the rate limiter rejects, the circuit breaker and retry logic are never reached.

Attribute overview

[Retry]

[Retry(MaxAttempts = 3, BackoffMs = 200, Jitter = true, PerAttemptTimeoutMs = 1_000)]

[RetryAttempt] on an int? or int parameter of a method under [Retry] passes the retry number instead of the caller's argument: null, 1, 2, … for int?, and 0, 1, 2, … for int.

[Timeout]

[Timeout(Ms = 5_000)]

[RateLimit]

[RateLimit(MaxPerSecond = 100, BurstSize = 10, Scope = RateLimitScope.Shared)]

[CircuitBreaker]

[CircuitBreaker(MaxFailures = 5, ResetMs = 1_000, HalfOpenProbes = 1, Fallback = nameof(FetchFallback))]

Method-level overrides

Apply attributes directly to methods to override the interface-level config for that method only:

[Retry(MaxAttempts = 3, BackoffMs = 200)]
public interface IExternalService
{
    ValueTask<string> FetchAsync(string id, CancellationToken ct); // uses interface-level

    [Retry(MaxAttempts = 1)]   // POST is not idempotent — one attempt only
    ValueTask PostAsync(string data, CancellationToken ct);
}

Method-level attributes shadow interface-level ones entirely for that method — they are not additive.

Failure surface

try
{
    var result = await service.FetchAsync("id", ct);
}
catch (ResilienceException ex) when (ex.Policy == ResiliencePolicy.CircuitBreaker)
{
    // circuit was open and no fallback was configured
}

Diagnostics

Documentation

Full docs live in docs/:

• Getting Started
• Attribute Reference
• Source Generator
• Performance
• Core concepts: Retry · Timeout · Rate Limit · Circuit Breaker · Execution Order
• Guides: Fallback · Method-Level Overrides · Result Return Types · DI Registration · Migrating to 2.0

License

MIT