Http resilience readme (#4663)

* Http resilience readme

* Update HttpStandardHedgingResilienceOptions.cs

* Apply suggestions from code review

Co-authored-by: martintmk <103487740+martintmk@users.noreply.github.com>

* Custom pipeline

* Fixup

* Better pipeline

---------

Co-authored-by: martintmk <103487740+martintmk@users.noreply.github.com>

src/Libraries/Microsoft.Extensions.Http.Resilience/Hedging/HttpStandardHedgingResilienceOptions.cs

@@ -22,7 +22,7 @@ namespace Microsoft.Extensions.Http.Resilience;
 /// <item><description>Total request timeout strategy applies an overall timeout to the execution,
 /// ensuring that the request including hedging attempts does not exceed the configured limit.</description></item>
 /// <item><description>The hedging strategy executes the requests against multiple endpoints in case the dependency is slow or returns a transient error.</description></item>
-/// <item><description>The bulkhead policy limits the maximum number of concurrent requests being send to the dependency.</description></item>
+/// <item><description>The rate limiter pipeline limits the maximum number of requests being send to the dependency.</description></item>
 /// <item><description>The circuit breaker blocks the execution if too many direct failures or timeouts are detected.</description></item>
 /// <item><description>The attempt timeout strategy limits each request attempt duration and throws if its exceeded.</description></item>
 /// </list>

src/Libraries/Microsoft.Extensions.Http.Resilience/Microsoft.Extensions.Http.Resilience.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <RootNamespace>Microsoft.Extensions.Http.Resilience</RootNamespace>
-    <Description>Resilience mechanisms for HTTP Client.</Description>
+    <Description>Resilience mechanisms for HttpClient.</Description>
     <Workstream>Resilience</Workstream>
   </PropertyGroup>
 

src/Libraries/Microsoft.Extensions.Http.Resilience/README.md

@@ -1,6 +1,6 @@
 # Microsoft.Extensions.Http.Resilience
 
-Resilience mechanisms for HTTP Client.
+Resilience mechanisms for `HttpClient` built on the [Polly framework](https://www.pollydocs.org/).
 
 ## Install the package
 
@@ -18,6 +18,60 @@ Or directly in the C# project file:
 </ItemGroup>
 ```
 
+## Usage Examples
+
+When configuring an HttpClient through the [HTTP client factory](https://learn.microsoft.com/dotnet/core/extensions/httpclient-factory) the following extensions can add a set of pre-configured hedging or resilience behaviors. These pipelines combine multiple resilience strategies with pre-configured defaults.
+- The total request timeout pipeline applies an overall timeout to the execution, ensuring that the request including hedging attempts, does not exceed the configured limit.
+- The retry pipeline retries the request in case the dependency is slow or returns a transient error.
+- The rate limiter pipeline limits the maximum number of requests being send to the dependency.
+- The circuit breaker blocks the execution if too many direct failures or timeouts are detected.
+- The attempt timeout pipeline limits each request attempt duration and throws if its exceeded.
+
+### Resilience
+
+The standard resilience pipeline makes use of the above strategies to ensure HTTP requests can be sent reliably.
+
+```csharp
+var clientBuilder = services.AddHttpClient("MyClient");
+
+clientBuilder.AddStandardResilienceHandler().Configure(o =>
+{
+    o.CircuitBreaker.MinimumThroughput = 10;
+});
+```
+
+### Hedging
+
+The standard hedging pipeline uses a pool of circuit breakers to ensure that unhealthy endpoints are not hedged against. By default, the selection from pool is based on the URL Authority (scheme + host + port). It is recommended that you configure the way the strategies are selected by calling the `SelectPipelineByAuthority()` extensions. The last three strategies are applied to each individual endpoint.
+
+```csharp
+var clientBuilder = services.AddHttpClient("MyClient");
+
+clientBuilder.AddStandardHedgingHandler().Configure(o =>
+{
+    o.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(10);
+});
+```
+
+### Custom Resilience
+
+For more granular control a custom pipeline can be constructed.
+
+```csharp
+var clientBuilder = services.AddHttpClient("MyClient");
+
+clientBuilder.AddResilienceHandler("myHandler", b =>
+{
+    b.AddFallback(new FallbackStrategyOptions<HttpResponseMessage>()
+    {
+        FallbackAction = _ => Outcome.FromResultAsValueTask(new HttpResponseMessage(HttpStatusCode.ServiceUnavailable))
+    })
+    .AddConcurrencyLimiter(100)
+    .AddRetry(new HttpRetryStrategyOptions())
+    .AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions())
+    .AddTimeout(new HttpTimeoutStrategyOptions());
+});
+```
 
 ## Feedback & Contributing