Merge branch 'main' into dotnet-8

CHANGELOG.md

@@ -1,3 +1,27 @@
+## 8.0.0-alpha.8
+
+* Updates for 8.0.0-alpha.7 by [@martincostello](https://github.com/martincostello) in https://github.com/App-vNext/Polly/pull/1433
+* Improve logging messages by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1436
+* Rename `BuilderName` to `Name` by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1437
+* Do not record null tags to meter by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1438
+* Fix telemetry test failures by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1439
+* Simplify OutcomeResilienceStrategy by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1440
+* Drop simple circuit breaker by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1444
+* Allow jitter for all backoff types by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1445
+* Rename `Attempt` to `AttemptNumber` by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1447
+* Hide `CircuitBreakerStateProvider.LastHandledOutcome` by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1446
+* Rename `ResilienceStrategyBuilder` to `CompositeStrategyBuilder` by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1448
+* Added `readonly` modifier to private fields which are never changed by [@Lehonti](https://github.com/Lehonti) in https://github.com/App-vNext/Polly/pull/1451
+* Reduced nesting levels through block-scoped `using`s and the inversion of an `if` block. by [@Lehonti](https://github.com/Lehonti) in https://github.com/App-vNext/Polly/pull/1453
+* Simplify file names by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1455
+* Improve `MultipleStrategiesBenchmark` by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1457
+* Elaborate about synchronous vs asynchronous executions by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1456
+* Fix some typos in XML docs by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1458
+* Make `ReactiveResilienceStrategy` public by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1460
+* Make the `ReactiveResilienceStrategy` type-safe by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1462
+* Use `StrategyHelper` for safe executions and drop redundant methods by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1463
+* Drop unnecessary allocation in circuit breaker by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1464
+
 ## 8.0.0-alpha.7
 
 * Introduce ResilienceStrategyBuilder.Validator by [@martintmk](https://github.com/martintmk) in https://github.com/App-vNext/Polly/pull/1412

Directory.Packages.props

@@ -2,7 +2,7 @@
   <PropertyGroup>
     <MicrosoftExtensionsVersion>8.0.0-preview.6.23329.7</MicrosoftExtensionsVersion>
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
-    <PollyVersion>8.0.0-alpha.7</PollyVersion>
+    <PollyVersion>8.0.0-alpha.8</PollyVersion>
   </PropertyGroup>
   <ItemGroup>
     <PackageVersion Include="coverlet.msbuild" Version="6.0.0" />
@@ -23,7 +23,7 @@
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.6.3" />
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="1.1.1" />
     <PackageVersion Include="MinVer" Version="4.3.0" />
-    <PackageVersion Include="Moq" Version="4.18.4" />
+    <PackageVersion Include="NSubstitute" Version="5.0.0" />
     <PackageVersion Include="Polly" Version="$(PollyVersion)" />
     <PackageVersion Include="Polly.Core" Version="$(PollyVersion)" />
     <PackageVersion Include="Polly.Extensions" Version="$(PollyVersion)" />

README.md

@@ -5,8 +5,8 @@
 > Major performance improvements are on the way! Please see our [blog post](https://www.thepollyproject.org/2023/03/03/we-want-your-feedback-introducing-polly-v8/) to learn more and provide feedback in the [related GitHub issue](https://github.com/App-vNext/Polly/issues/1048).
 >
 > :rotating_light::rotating_light: **Polly v8 feature-complete!** :rotating_light::rotating_light:
-> - Polly v8 Alpha 7 is now available on [NuGet.org](https://www.nuget.org/packages/Polly/8.0.0-alpha.7)
-> - The Alpha 7 version is considered feature-complete. After completing [review of the API](https://github.com/App-vNext/Polly/pull/1233) to address unresolved issues, we will move on to a Beta release.
+> - Polly v8 Alpha 8 is now available on [NuGet.org](https://www.nuget.org/packages/Polly/8.0.0-alpha.8)
+> - The Alpha 8 version is considered feature-complete. After completing [review of the API](https://github.com/App-vNext/Polly/pull/1233) to address unresolved issues, we will move on to a Beta release.
 > - The v8 docs are not yet finished, but you can take a look at sample code in these locations:
 >     - Within the repo's new [Samples folder](https://github.com/App-vNext/Polly/tree/main/samples)
 >     - By reading `Polly.Core`'s [README](https://github.com/App-vNext/Polly/blob/main/src/Polly.Core/README.md)

bench/BenchmarkDotNet.Artifacts/results/Polly.Core.Benchmarks.MultipleStrategiesBenchmark-report-github.md

@@ -11,8 +11,8 @@ LaunchCount=2  WarmupCount=10
 ```
 |                                         Method |     Mean |     Error |    StdDev | Ratio | RatioSD |   Gen0 | Allocated | Alloc Ratio |
 |----------------------------------------------- |---------:|----------:|----------:|------:|--------:|-------:|----------:|------------:|
-|             ExecuteStrategyPipeline_Generic_V7 | 2.318 μs | 0.0253 μs | 0.0355 μs |  1.00 |    0.00 | 0.1106 |    2824 B |        1.00 |
-|             ExecuteStrategyPipeline_Generic_V8 | 2.044 μs | 0.0095 μs | 0.0140 μs |  0.88 |    0.02 |      - |      72 B |        0.03 |
-|    ExecuteStrategyPipeline_GenericTelemetry_V8 | 2.950 μs | 0.0059 μs | 0.0089 μs |  1.27 |    0.02 |      - |      72 B |        0.03 |
-|          ExecuteStrategyPipeline_NonGeneric_V8 | 2.295 μs | 0.0176 μs | 0.0264 μs |  0.99 |    0.01 |      - |      72 B |        0.03 |
-| ExecuteStrategyPipeline_NonGenericTelemetry_V8 | 3.153 μs | 0.0058 μs | 0.0085 μs |  1.36 |    0.02 |      - |      72 B |        0.03 |
+|             ExecuteStrategyPipeline_Generic_V7 | 2.523 μs | 0.0207 μs | 0.0303 μs |  1.00 |    0.00 | 0.1106 |    2824 B |        1.00 |
+|             ExecuteStrategyPipeline_Generic_V8 | 1.997 μs | 0.0079 μs | 0.0110 μs |  0.79 |    0.01 |      - |      40 B |        0.01 |
+|    ExecuteStrategyPipeline_GenericTelemetry_V8 | 2.909 μs | 0.0111 μs | 0.0166 μs |  1.15 |    0.01 |      - |      40 B |        0.01 |
+|          ExecuteStrategyPipeline_NonGeneric_V8 | 2.286 μs | 0.0101 μs | 0.0152 μs |  0.91 |    0.01 |      - |      40 B |        0.01 |
+| ExecuteStrategyPipeline_NonGenericTelemetry_V8 | 3.223 μs | 0.0146 μs | 0.0215 μs |  1.28 |    0.02 |      - |      40 B |        0.01 |

bench/Polly.Core.Benchmarks/TelemetryBenchmark.cs

@@ -1,6 +1,5 @@
 using System.Diagnostics.Metrics;
 using Microsoft.Extensions.Logging.Abstractions;
-using Polly.Extensions.Telemetry;
 using Polly.Telemetry;
 
 namespace Polly.Core.Benchmarks;

eng/Test.targets

@@ -15,7 +15,7 @@
     <PackageReference Include="FluentAssertions" />
     <PackageReference Include="GitHubActionsTestLogger" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" />
-    <PackageReference Include="Moq" />
+    <PackageReference Include="NSubstitute" />
     <PackageReference Include="ReportGenerator" PrivateAssets="all" />
     <PackageReference Include="xunit" />
     <PackageReference Include="xunit.runner.visualstudio" PrivateAssets="all" />

samples/Extensibility/Program.cs

@@ -4,7 +4,7 @@
 // ------------------------------------------------------------------------
 // Usage of custom strategy
 // ------------------------------------------------------------------------
-var strategy = new ResilienceStrategyBuilder()
+var strategy = new CompositeStrategyBuilder()
     // This is custom extension defined in this sample
     .AddMyResilienceStrategy(new MyResilienceStrategyOptions
     {
@@ -23,7 +23,7 @@
 // SIMPLE EXTENSIBILITY MODEL (INLINE STRATEGY)
 // ------------------------------------------------------------------------
 
-strategy = new ResilienceStrategyBuilder()
+strategy = new CompositeStrategyBuilder()
     // Just add the strategy instance directly
     .AddStrategy(new MySimpleStrategy())
     .Build();
@@ -76,7 +76,10 @@ public class MyResilienceStrategyOptions : ResilienceStrategyOptions
 // 2. Create a custom resilience strategy that derives from ResilienceStrategy
 // ------------------------------------------------------------------------
 
-// The strategy should be internal and not exposed as part of any public API. Instead, expose options and extensions for resilience strategy builder.
+// The strategy should be internal and not exposed as part of any public API.
+// Instead, expose options and extensions for resilience strategy builder.
+//
+// For reactive startegies, you can use ReactiveResilienceStrategy<T> as base class.
 internal class MyResilienceStrategy : ResilienceStrategy
 {
     private readonly ResilienceStrategyTelemetry telemetry;
@@ -119,13 +122,13 @@ protected override async ValueTask<Outcome<TResult>> ExecuteCore<TResult, TState
 }
 
 // ------------------------------------------------------------------------
-// 3. Expose new extensions for ResilienceStrategyBuilder
+// 3. Expose new extensions for CompositeStrategyBuilder
 // ------------------------------------------------------------------------
 
 public static class MyResilienceStrategyExtensions
 {
-    // Add new extension that works for both "ResilienceStrategyBuilder" and "ResilienceStrategyBuilder<T>"
-    public static TBuilder AddMyResilienceStrategy<TBuilder>(this TBuilder builder, MyResilienceStrategyOptions options) where TBuilder : ResilienceStrategyBuilderBase
+    // Add new extension that works for both "CompositeStrategyBuilder" and "CompositeStrategyBuilder<T>"
+    public static TBuilder AddMyResilienceStrategy<TBuilder>(this TBuilder builder, MyResilienceStrategyOptions options) where TBuilder : CompositeStrategyBuilderBase
         => builder.AddStrategy(
             // Provide a factory that creates the strategy
             context => new MyResilienceStrategy(context.Telemetry, options),

samples/GenericStrategies/Program.cs

@@ -5,13 +5,13 @@
 using System.Net;
 
 // ----------------------------------------------------------------------------
-// Create a generic resilience strategy using ResilienceStrategyBuilder<T>
+// Create a generic resilience strategy using CompositeStrategyBuilder<T>
 // ----------------------------------------------------------------------------
 
-// The generic ResilienceStrategyBuilder<T> creates a ResilienceStrategy<T>
+// The generic CompositeStrategyBuilder<T> creates a ResilienceStrategy<T>
 // that can execute synchronous and asynchronous callbacks that return T.
 
-ResilienceStrategy<HttpResponseMessage> strategy = new ResilienceStrategyBuilder<HttpResponseMessage>()
+ResilienceStrategy<HttpResponseMessage> strategy = new CompositeStrategyBuilder<HttpResponseMessage>()
     .AddFallback(new FallbackStrategyOptions<HttpResponseMessage>
     {
         FallbackAction = _ =>
@@ -43,7 +43,7 @@
     })
     .AddTimeout(new TimeoutStrategyOptions
     {
-        Timeout = TimeSpan.FromMilliseconds(500),
+        Timeout = TimeSpan.FromSeconds(1),
         // Register user callback called whenever timeout occurs
         OnTimeout = _ => { Console.WriteLine("Timeout occurred!"); return default; }
     })

samples/Intro/Program.cs

@@ -3,13 +3,13 @@
 using Polly.Timeout;
 
 // ------------------------------------------------------------------------
-// 1. Create a simple resilience strategy using ResilienceStrategyBuilder
+// 1. Create a simple resilience strategy using CompositeStrategyBuilder
 // ------------------------------------------------------------------------
 
-// The ResilienceStrategyBuilder creates a ResilienceStrategy
+// The CompositeStrategyBuilder creates a ResilienceStrategy
 // that can be executed synchronously or asynchronously
 // and for both void and result-returning user-callbacks.
-ResilienceStrategy strategy = new ResilienceStrategyBuilder()
+ResilienceStrategy strategy = new CompositeStrategyBuilder()
     // Use convenience extension that accepts TimeSpan
     .AddTimeout(TimeSpan.FromSeconds(5)) 
     .Build();
@@ -37,7 +37,7 @@
 // 3. Create and execute a pipeline of strategies
 // ------------------------------------------------------------------------
 
-strategy = new ResilienceStrategyBuilder()
+strategy = new CompositeStrategyBuilder()
     // Add retries using the options
     .AddRetry(new RetryStrategyOptions
     {
@@ -51,15 +51,15 @@
             _ => PredicateResult.False
         },
         // Register user callback called whenever retry occurs
-        OnRetry = args => { Console.WriteLine($"Retrying...{args.Arguments.Attempt} attempt"); return default; },
+        OnRetry = args => { Console.WriteLine($"Retrying...{args.Arguments.AttemptNumber} attempt"); return default; },
         BaseDelay = TimeSpan.FromMilliseconds(400),
         BackoffType = RetryBackoffType.Constant,
         RetryCount = 3
     })
     // Add timeout using the options
     .AddTimeout(new TimeoutStrategyOptions
     {
-        Timeout = TimeSpan.FromMilliseconds(500),
+        Timeout = TimeSpan.FromSeconds(1),
         // Register user callback called whenever timeout occurs
         OnTimeout = args =>
         {

samples/README.md

@@ -2,8 +2,8 @@
 
 This repository contains a solution with basic examples demonstrating the creation and utilization of Polly strategies.
 
-- [`Intro`](./Intro) - This section serves as an introduction to Polly. It demonstrates how to use `ResilienceStrategyBuilder` to create a `ResilienceStrategy`, which can be used to execute various user-provided callbacks.
-- [`GenericStrategies`](./GenericStrategies) - This example showcases how to use `ResilienceStrategyBuilder<T>` to create a generic `ResilienceStrategy<T>`.
+- [`Intro`](./Intro) - This section serves as an introduction to Polly. It demonstrates how to use `CompositeStrategyBuilder` to create a `ResilienceStrategy`, which can be used to execute various user-provided callbacks.
+- [`GenericStrategies`](./GenericStrategies) - This example showcases how to use `CompositeStrategyBuilder<T>` to create a generic `ResilienceStrategy<T>`.
 - [`Retries`](./Retries) - This part explains how to configure a retry resilience strategy.
 - [`Extensibility`](./Extensibility) - In this part, you can learn how Polly can be extended with custom resilience strategies.
 - [`DependencyInjection`](./DependencyInjection) - This section demonstrates the integration of Polly with `IServiceCollection`.

samples/Retries/Program.cs

@@ -9,7 +9,7 @@
 // 1. Create a retry strategy that handles all exceptions
 // ------------------------------------------------------------------------
 
-ResilienceStrategy strategy = new ResilienceStrategyBuilder()
+ResilienceStrategy strategy = new CompositeStrategyBuilder()
     // Default retry options handle all exceptions
     .AddRetry(new RetryStrategyOptions())
     .Build();
@@ -21,7 +21,7 @@
 // 2. Customize the retry behavior
 // ------------------------------------------------------------------------
 
-strategy = new ResilienceStrategyBuilder()
+strategy = new CompositeStrategyBuilder()
     .AddRetry(new RetryStrategyOptions
     {
         // Specify what exceptions should be retried using PredicateBuilder
@@ -31,7 +31,8 @@
 
         // The recommended backoff type for HTTP scenarios
         // See here for more information: https://github.com/App-vNext/Polly/wiki/Retry-with-jitter#more-complex-jitter
-        BackoffType = RetryBackoffType.ExponentialWithJitter
+        BackoffType = RetryBackoffType.Exponential,
+        UseJitter = true
     })
     .Build();
 
@@ -42,7 +43,7 @@
 // 3. Register the callbacks
 // ------------------------------------------------------------------------
 
-strategy = new ResilienceStrategyBuilder()
+strategy = new CompositeStrategyBuilder()
     .AddRetry(new RetryStrategyOptions
     {
         // Specify what exceptions should be retried using switch expressions
@@ -53,7 +54,7 @@
         },
         OnRetry = outcome =>
         {
-            Console.WriteLine($"Retrying attempt {outcome.Arguments.Attempt}...");
+            Console.WriteLine($"Retrying attempt {outcome.Arguments.AttemptNumber}...");
             return default;
         }
     })
@@ -66,7 +67,7 @@
 // 4. Create an HTTP retry strategy that handles both exceptions and results
 // ------------------------------------------------------------------------
 
-ResilienceStrategy<HttpResponseMessage> httpStrategy = new ResilienceStrategyBuilder<HttpResponseMessage>()
+ResilienceStrategy<HttpResponseMessage> httpStrategy = new CompositeStrategyBuilder<HttpResponseMessage>()
     .AddRetry(new RetryStrategyOptions<HttpResponseMessage>
     {
         // Specify what exceptions or results should be retried