feat: Add comprehensive documentation for HttpClient resilience patterns including standard, hedging, and custom pipelines

Author: aalmada

.github/skills/csharp-http-resilience/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: csharp-http-resilience
+description: Add retry, circuit breaker, timeout, hedging, and rate-limiting to HttpClient-based .NET code using Microsoft.Extensions.Http.Resilience (built on Polly v8). Covers AddStandardResilienceHandler, AddResilienceHandler, AddStandardHedgingHandler, ResiliencePipelineBuilder for static clients, Refit integration, and the ResilienceHandler wrapper. Trigger whenever the user writes, reviews, or asks about HTTP resilience, retries, circuit breakers, timeouts, transient fault handling, AddStandardResilienceHandler, AddResilienceHandler, AddStandardHedgingHandler, Polly, IHttpClientFactory resilience, or HttpClient reliability in .NET — even if they don't mention Microsoft.Extensions.Http.Resilience by name. Always prefer this skill over guessing; the handler-stacking rules, retry safety for non-idempotent methods, TimeoutRejectedException vs TimeoutException distinction, and static-client wiring all have non-obvious failure modes. Also trigger when the deprecated Microsoft.Extensions.Http.Polly package is used — it should be replaced with this package.
+---
+
+# Microsoft.Extensions.Http.Resilience Skill
+
+`Microsoft.Extensions.Http.Resilience` is the official .NET integration layer between `IHttpClientFactory` and Polly v8 resilience pipelines. It replaces the deprecated `Microsoft.Extensions.Http.Polly` package and provides first-class DI support for retry, circuit breaker, timeout, rate limiting, and hedging.
+
+**NuGet**: `<PackageReference Include="Microsoft.Extensions.Http.Resilience" />`
+
+## Quick reference
+
+| Topic | See |
+|-------|-----|
+| `AddStandardResilienceHandler`, defaults pipeline, DisableFor, global defaults | [standard-handler.md](references/standard-handler.md) |
+| `AddStandardHedgingHandler`, routing strategies, SelectPipelineByAuthority | [hedging-handler.md](references/hedging-handler.md) |
+| `AddResilienceHandler` custom pipelines, HttpRetryStrategyOptions, dynamic reload | [custom-pipeline.md](references/custom-pipeline.md) |
+| `ResiliencePipelineBuilder` + `ResilienceHandler` for static/singleton clients | [static-clients.md](references/static-clients.md) |
+| Refit integration (DI-registered and manually-constructed) | [refit-integration.md](references/refit-integration.md) |
+
+## Two approaches
+
+### 1. IHttpClientFactory-based (recommended)
+
+Wire resilience into the `IHttpClientBuilder` chain during DI registration. This is the idiomatic approach for typed or named clients.
+
+```csharp
+// Typed client — single method, all defaults
+builder.Services
+    .AddHttpClient<MyApiClient>(c => c.BaseAddress = new("https://api.example.com"))
+    .AddStandardResilienceHandler();
+
+// Named client — custom pipeline
+services.AddHttpClient("payments")
+    .AddResilienceHandler("PaymentsPipeline", pipeline =>
+    {
+        pipeline.AddRetry(new HttpRetryStrategyOptions { MaxRetryAttempts = 2 });
+        pipeline.AddTimeout(TimeSpan.FromSeconds(10));
+    });
+```
+
+### 2. Static / manually-constructed HttpClient
+
+When you construct `HttpClient` directly (e.g., Refit with scoped DI, or a singleton not owned by DI), build the pipeline and wrap the handler chain manually. See [static-clients.md](references/static-clients.md).
+
+## Critical rules
+
+- **Never stack resilience handlers.** Only add _one_ resilience handler per client. If you need multiple strategies combine them inside a single `AddResilienceHandler` call.
+- **Retry is unsafe for non-idempotent methods.** Always call `options.Retry.DisableForUnsafeHttpMethods()` (or `DisableFor(HttpMethod.Post, ...)`) when POST/PUT/DELETE mutate state.
+- **Timeout exception type.** Polly throws `TimeoutRejectedException`, not `TimeoutException`. When writing `ShouldHandle` predicates in a retry that sits outside a timeout, handle `TimeoutRejectedException`.
+- **Circuit breaker per authority.** When using a circuit breaker on named clients shared across multiple host names, call `.SelectPipelineByAuthority()` so each host gets its own breaker state.
+- **`Microsoft.Extensions.Http.Polly` is deprecated.** Replace any `AddPolicyHandler` / `AddTransientHttpErrorPolicy` calls with the APIs in this skill.

.github/skills/csharp-http-resilience/references/custom-pipeline.md

@@ -0,0 +1,104 @@
+# Custom Resilience Pipelines
+
+Use `AddResilienceHandler` when you need full control over which strategies run and in what order. You get the same Polly building blocks as the standard handler, but assembled manually.
+
+## Basic shape
+
+```csharp
+services.AddHttpClient<PaymentsClient>(c => c.BaseAddress = new("https://pay.example.com"))
+    .AddResilienceHandler("PaymentsPipeline", pipeline =>
+    {
+        // Order matters: outermost strategy listed first
+        pipeline.AddRetry(new HttpRetryStrategyOptions
+        {
+            MaxRetryAttempts = 2,
+            BackoffType = DelayBackoffType.Exponential,
+            UseJitter = true,
+            Delay = TimeSpan.FromMilliseconds(500),
+            // Safe for idempotent GETs, but be careful with mutations
+            ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
+                .HandleResult(r => (int)r.StatusCode >= 500 || r.StatusCode == HttpStatusCode.RequestTimeout)
+                .Handle<HttpRequestException>()
+        });
+
+        pipeline.AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions
+        {
+            SamplingDuration = TimeSpan.FromSeconds(30),
+            FailureRatio = 0.5,
+            MinimumThroughput = 5,
+            BreakDuration = TimeSpan.FromSeconds(30),
+            ShouldHandle = new PredicateBuilder<HttpResponseMessage>()
+                .HandleResult(r => (int)r.StatusCode >= 500)
+                .Handle<HttpRequestException>()
+        });
+
+        pipeline.AddTimeout(TimeSpan.FromSeconds(15));
+    });
+```
+
+## HttpRetryStrategyOptions key properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `MaxRetryAttempts` | Number of retries (not attempts) | 3 |
+| `BackoffType` | `Constant`, `Linear`, `Exponential` | `Exponential` |
+| `Delay` | Base delay between attempts | 2 s |
+| `UseJitter` | Add randomness to spread retries | `true` |
+| `ShouldHandle` | What to retry on | 5xx, 408, 429, `HttpRequestException`, `TimeoutRejectedException` |
+
+## HttpCircuitBreakerStrategyOptions key properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `FailureRatio` | Fraction of failures to trip breaker | 0.1 (10 %) |
+| `MinimumThroughput` | Min requests before ratio applies | 100 |
+| `SamplingDuration` | Sliding window | 30 s |
+| `BreakDuration` | How long breaker stays open | 5 s |
+
+## TimeoutRejectedException gotcha
+
+When a retry wraps a timeout, Polly raises `TimeoutRejectedException` (not `TimeoutException`) when the attempt times out. If your `ShouldHandle` doesn't include it, the retry won't fire:
+
+```csharp
+// Wrong — TimeoutException is NOT what Polly throws
+.Handle<TimeoutException>()
+
+// Correct
+.Handle<TimeoutRejectedException>()
+// or just don't specify Handle<> for it — HttpRetryStrategyOptions handles it by default
+```
+
+Using `HttpRetryStrategyOptions` (the HTTP-specific type) rather than `RetryStrategyOptions<HttpResponseMessage>` makes this easier — it comes with sensible defaults already including `TimeoutRejectedException`.
+
+## Dynamic reload from configuration
+
+Use the two-argument overload to reload options at runtime without restarting:
+
+```csharp
+services.AddHttpClient<SearchClient>()
+    .AddResilienceHandler(
+        "SearchPipeline",
+        (pipeline, context) =>
+        {
+            // Reloads whenever IOptionsMonitor<HttpRetryStrategyOptions>("SearchRetry") changes
+            context.EnableReloads<HttpRetryStrategyOptions>("SearchRetry");
+
+            var retryOptions = context.GetOptions<HttpRetryStrategyOptions>("SearchRetry");
+            pipeline.AddRetry(retryOptions);
+        });
+```
+
+Configure the named options in `appsettings.json` under the matching key and bind with `services.Configure<HttpRetryStrategyOptions>("SearchRetry", config.GetSection("SearchRetry"))`.
+
+## Per-authority circuit breaker
+
+If a named client talks to multiple host names (via routing or redirects), isolate circuit breaker state per authority so one unhealthy host doesn't trip the breaker for others:
+
+```csharp
+services.AddHttpClient("multi-region")
+    .AddResilienceHandler("MultiRegionPipeline", pipeline =>
+    {
+        pipeline.AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions());
+    })
+    .SelectPipelineByAuthority();
+```

.github/skills/csharp-http-resilience/references/hedging-handler.md

@@ -0,0 +1,80 @@
+# Hedging Handler
+
+Hedging is a different resilience pattern from retry: instead of waiting for a failure before retrying, it proactively issues a second (or third) request in parallel when the first one is slow. Use hedging when latency matters more than request volume.
+
+## When to prefer hedging over retry
+
+- **Retry**: best when the dependency is occasionally down or rate-limiting. Tolerates higher latency.
+- **Hedging**: best when the dependency is usually available but sometimes slow (tail latency). Doubles request volume but halves p99.
+
+## Basic usage
+
+```csharp
+services.AddHttpClient<SearchClient>(c => c.BaseAddress = new("https://search.example.com"))
+    .AddStandardHedgingHandler();
+```
+
+## Default hedging pipeline (outermost → innermost, per attempt)
+
+| Order | Strategy | Default |
+|-------|----------|---------|
+| 1 | Total request timeout | 30 s |
+| 2 | Hedging | Min 1 attempt, max 10 concurrent, 2 s delay before hedging |
+| 3 | Rate limiter (per endpoint) | Queue: 0, Permit: 1 000 |
+| 4 | Circuit breaker (per endpoint) | 10 % failure ratio, 100 req minimum, 30 s window, 5 s break |
+| 5 | Attempt timeout (per endpoint) | 10 s |
+
+The per-endpoint circuit breaker ensures one slow endpoint doesn't cascade to healthy ones.
+
+## SelectPipelineByAuthority (important)
+
+The circuit breaker pool is keyed by URL authority by default. Make this explicit to avoid accidentally sharing state across different base addresses:
+
+```csharp
+services.AddHttpClient("search")
+    .AddStandardHedgingHandler()
+    .SelectPipelineByAuthority();
+```
+
+## Weighted routing (A/B testing)
+
+```csharp
+services.AddHttpClient<SearchClient>()
+    .AddStandardHedgingHandler(builder =>
+    {
+        builder.ConfigureWeightedGroups(opts =>
+        {
+            opts.SelectionMode = WeightedGroupSelectionMode.EveryAttempt;
+            opts.Groups.Add(new WeightedUriEndpointGroup
+            {
+                Endpoints =
+                {
+                    new() { Uri = new("https://search-v2.example.com"), Weight = 10 },
+                    new() { Uri = new("https://search.example.com"), Weight = 90 }
+                }
+            });
+        });
+    });
+```
+
+## Ordered failover
+
+```csharp
+services.AddHttpClient<SearchClient>()
+    .AddStandardHedgingHandler(builder =>
+    {
+        builder.ConfigureOrderedGroups(opts =>
+        {
+            opts.Groups.Add(new UriEndpointGroup
+            {
+                Endpoints =
+                {
+                    new() { Uri = new("https://primary.example.com"), Weight = 97 },
+                    new() { Uri = new("https://fallback.example.com"), Weight = 3 }
+                }
+            });
+        });
+    });
+```
+
+The maximum number of hedging attempts equals the number of configured endpoint groups.

.github/skills/csharp-http-resilience/references/refit-integration.md

@@ -0,0 +1,65 @@
+# Refit Integration
+
+Refit clients can be wired with resilience in two ways depending on whether they are managed by `IHttpClientFactory` (cleaner, recommended) or constructed manually (needed when clients are scoped).
+
+## IHttpClientFactory-based (recommended)
+
+Use `AddRefitClient<T>()` from `Refit.HttpClientFactory`, then chain `AddResilienceHandler` or `AddStandardResilienceHandler` exactly like any other typed client:
+
+```csharp
+// Simple — standard resilience, no custom options
+services
+    .AddRefitClient<IOrdersClient>()
+    .ConfigureHttpClient(c => c.BaseAddress = new("https://orders.example.com"))
+    .AddStandardResilienceHandler(opts =>
+    {
+        opts.Retry.DisableForUnsafeHttpMethods(); // POST/PUT/DELETE not idempotent
+    });
+
+// Custom pipeline
+services
+    .AddRefitClient<ISearchClient>()
+    .ConfigureHttpClient(c => c.BaseAddress = new("https://search.example.com"))
+    .AddResilienceHandler("SearchPipeline", pipeline =>
+    {
+        pipeline.AddRetry(new HttpRetryStrategyOptions { MaxRetryAttempts = 5 });
+        pipeline.AddTimeout(TimeSpan.FromSeconds(8));
+    });
+```
+
+## Manually-constructed Refit (Blazor scoped pattern)
+
+In Blazor Server you often need scoped clients that capture per-circuit services (auth tokens, tenant context). Use the static-client pattern from [static-clients.md](static-clients.md) and pass the final `HttpClient` to `RestService.For<T>`:
+
+```csharp
+services.AddScoped<IOrdersClient>(sp =>
+{
+    var pipeline = sp.GetRequiredService<ResiliencePipeline<HttpResponseMessage>>();
+    var tokenService = sp.GetRequiredService<TokenService>();
+    var tenantService = sp.GetRequiredService<TenantService>();
+
+    // Handler chain: Resilience → Auth → Tenant → Network
+    var networkHandler = new HttpClientHandler();
+    var tenantHandler = new TenantHeaderHandler(tenantService) { InnerHandler = networkHandler };
+    var authHandler = new AuthHandler(tokenService) { InnerHandler = tenantHandler };
+    var resilienceHandler = new ResilienceHandler(pipeline) { InnerHandler = authHandler };
+
+    var httpClient = new HttpClient(resilienceHandler) { BaseAddress = new("https://api.example.com") };
+    return RestService.For<IOrdersClient>(httpClient);
+});
+```
+
+The shared `ResiliencePipeline<HttpResponseMessage>` is registered as a singleton (built once at startup) and injected. See [static-clients.md](static-clients.md) for how to build and register it.
+
+## Choosing between the two
+
+| Scenario | Approach |
+|----------|----------|
+| Standalone API / worker / console app | `AddRefitClient<T>().AddStandardResilienceHandler()` |
+| Blazor Server with per-circuit auth/tenant | Manual `RestService.For<T>(httpClient)` with `ResilienceHandler` |
+| Multiple clients sharing same pipeline | Build shared `ResiliencePipeline<HttpResponseMessage>` singleton |
+| Clients needing different resilience options | Separate `AddResilienceHandler` calls per client |
+
+## Common mistake: registering scoped Refit clients as singletons
+
+If you register a Refit client as `AddSingleton` but it captures a scoped `TokenService`, you'll get a captive dependency bug — the first request claims a token and every subsequent request uses the same stale token. Always register as `AddScoped` when the client captures scoped services.

.github/skills/csharp-http-resilience/references/standard-handler.md

@@ -0,0 +1,77 @@
+# Standard Resilience Handler
+
+`AddStandardResilienceHandler()` wires five Polly strategies in a sensible default order with out-of-the-box settings that cover most APIs. It is the right starting point unless you specifically need hedging or a hand-tuned pipeline.
+
+## Default pipeline (outermost → innermost)
+
+| Order | Strategy | What it does | Default |
+|-------|----------|-------------|---------|
+| 1 | Rate limiter | Caps concurrent requests | Queue: 0, Permit: 1 000 |
+| 2 | Total timeout | Overall time limit including retries | 30 s |
+| 3 | Retry | Retries on transient errors | 3 attempts, exponential backoff + jitter, 2 s base |
+| 4 | Circuit breaker | Opens on sustained failures | 10 % failure ratio, min 100 requests, 30 s window, 5 s break |
+| 5 | Attempt timeout | Per-attempt time limit | 10 s |
+
+**Handled by retry and circuit breaker**: HTTP 5xx, 408, 429, `HttpRequestException`, `TimeoutRejectedException`.
+
+## Basic usage
+
+```csharp
+// Typed client
+services.AddHttpClient<WeatherClient>(c => c.BaseAddress = new("https://api.weather.com"))
+    .AddStandardResilienceHandler();
+
+// Named client
+services.AddHttpClient("external-api")
+    .AddStandardResilienceHandler();
+```
+
+## Customising options
+
+Pass a delegate to override individual strategy options without replacing the whole pipeline:
+
+```csharp
+services.AddHttpClient<OrdersClient>(c => c.BaseAddress = new("https://orders.example.com"))
+    .AddStandardResilienceHandler(options =>
+    {
+        // Tighten the total timeout for latency-sensitive callers
+        options.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(10);
+
+        // Fewer retries for this client
+        options.Retry.MaxRetryAttempts = 2;
+
+        // Don't retry writes — risks duplicate records
+        options.Retry.DisableForUnsafeHttpMethods();
+
+        // Tighter circuit breaker
+        options.CircuitBreaker.FailureRatio = 0.3;
+        options.CircuitBreaker.MinimumThroughput = 20;
+    });
+```
+
+### DisableFor vs DisableForUnsafeHttpMethods
+
+- `DisableFor(HttpMethod.Post, HttpMethod.Delete)` — explicit list
+- `DisableForUnsafeHttpMethods()` — disables retries for POST, PUT, PATCH, DELETE, CONNECT per RFC 7231 idempotency rules
+
+Always use one of these when the API performs state mutations.
+
+## Global defaults
+
+Apply a resilience handler to all registered `HttpClient` instances in one go, then selectively override:
+
+```csharp
+// All clients get standard resilience
+services.ConfigureHttpClientDefaults(b => b.AddStandardResilienceHandler());
+
+// High-priority client: swap to hedging and remove the standard handler
+services.AddHttpClient("priority")
+    .RemoveAllResilienceHandlers()
+    .AddStandardHedgingHandler();
+```
+
+`RemoveAllResilienceHandlers()` clears every previously registered resilience handler, giving you a clean slate. Use it after `ConfigureHttpClientDefaults` when a specific client needs different behaviour.
+
+## Aspire integration
+
+When using .NET Aspire service defaults (`AddServiceDefaults`), resilience is pre-configured via `ConfigureHttpClientDefaults`. Review [BookStore.ServiceDefaults/AGENTS.md](../../../../src/BookStore.ServiceDefaults/AGENTS.md) to understand what's already wired in before adding another handler.