ZeroAlloc.Resilience 3.3.5

ZeroAlloc.Resilience

Retry, timeout, rate limiting and circuit breaking for .NET, declared as attributes on an interface and compiled into a proxy: a source-generated alternative to Polly with no allocation on the happy path.

Why ZeroAlloc.Resilience

• 0 B per successful call through [Retry] and [CircuitBreaker], asserted by tests on every run. Polly v8 allocates a 64 B ResilienceContext per call.
• 14.7× and 15.0× faster than Polly v8 on the retry and circuit-breaker happy paths, and 5.9× faster with all four policies stacked, measured in the same run.
• Works under NativeAOT and trimming. The proxy is plain generated code with no reflection, published as a NativeAOT app in CI.
• Mistakes surface at compile time. A misspelled fallback, an invalid attribute value or a timeout on a method without a CancellationToken is a compiler diagnostic.

Install

dotnet add package ZeroAlloc.Resilience

Quick start

using Microsoft.Extensions.DependencyInjection;
using ZeroAlloc.Resilience;

var services = new ServiceCollection();
services.AddWeatherClientResilience<FlakyWeatherClient>(); // generated: registers the proxy

var client = services.BuildServiceProvider().GetRequiredService<IWeatherClient>();
Console.WriteLine(await client.GetForecastAsync("Amsterdam", CancellationToken.None));
// Amsterdam: sunny, after 3 attempts

[Retry(MaxAttempts = 3, BackoffMs = 100, Jitter = true)]
[Timeout(Ms = 5_000)]
[CircuitBreaker(MaxFailures = 5, ResetMs = 30_000)]
public interface IWeatherClient
{
    ValueTask<string> GetForecastAsync(string city, CancellationToken ct);
}

public sealed class FlakyWeatherClient : IWeatherClient
{
    private int _calls;

    public ValueTask<string> GetForecastAsync(string city, CancellationToken ct)
        => ++_calls < 3
            ? throw new HttpRequestException($"attempt {_calls} failed")
            : ValueTask.FromResult($"{city}: sunny, after {_calls} attempts");
}

The first two calls throw, the proxy retries, and the caller only sees the result. Callers inject IWeatherClient as usual.

What you get

• Retry with exponential backoff, jitter, a per-attempt timeout and a cap on the delay.
• Timeout over the whole operation, retries and backoff included.
• Rate limiting with a lock-free token bucket, shared per interface or per proxy.
• Circuit breaker with half-open probing and an optional fallback method.
• A fixed, predictable order: rate limit, circuit breaker, timeout, retry, whatever order you write the attributes in.
• Exceptions or Results: return a ZeroAlloc.Results Result<T> and policy failures come back as a failure instead of a throw.
• Result-aware retry: retry only the failures you call transient, and honour Retry-After hints.
• Per-method overrides of the interface-level policies, for example one attempt for a non-idempotent POST.
• One-line DI registration through a generated Add{Service}Resilience<TImpl>() extension.
• Compile-time diagnostics ZR0001–ZR0013: the full list. Every attribute property: attribute reference.

Performance

Against Polly.Core 8.8.0 on .NET 10.0.13, measured 2026-10-15. Allocations are exact; speed is a same-run ratio, because the benchmark host is a shared VM.

With all policies stacked, the 144 B is the linked CancellationTokenSource and timer that [Timeout] needs; without [Timeout] the proxy allocates nothing. Polly walks a delegate chain per call; ZA emits one method with the policy checks inline. Failure paths, an open circuit and the full method: docs/performance.md.

Learn more

• Documentation: resilience.zeroalloc.net
• Getting started, execution order, Result return types and migrating to 3.0
• Related packages: ZeroAlloc.Rest for source-generated HTTP clients, ZeroAlloc.Cache for caching proxies, ZeroAlloc.Telemetry for tracing and metrics proxies
• Contributing: issues and pull requests are welcome on GitHub
• License: MIT