Simmy API review Part 1 (#1909)

peter-csala · web-flow · commit 24a86c843d75 · 2024-01-22T09:55:32.000Z
diff --git a/docs/chaos/index.md b/docs/chaos/index.md
@@ -51,6 +51,6 @@ All the strategies' options implement the [`MonkeyStrategyOptions`](xref:Polly.S
 | `InjectionRate`          | 0.001         | A decimal between 0 and 1 inclusive. The strategy will inject the chaos, randomly, that proportion of the time, e.g.: if 0.2, twenty percent of calls will be randomly affected; if 0.01, one percent of calls; if 1, all calls. |
 | `InjectionRateGenerator` | `null`        | Generates the injection rate for a given execution, which the value should be between [0, 1] (inclusive).                                                                                                                        |
 | `Enabled`                | `false`       | Determines whether the strategy is enabled or not.                                                                                                                                                                               |
-| `EnabledGenerator`       | `null`        | The generator that indicates whether the chaos strategy is enabled for a given execution.                                                                                                                          |
+| `EnabledGenerator`       | `null`        | The generator that indicates whether the chaos strategy is enabled for a given execution.                                                                                                                                        |
 
 [simmy]: https://github.com/Polly-Contrib/Simmy
diff --git a/docs/chaos/latency.md b/docs/chaos/latency.md
@@ -50,14 +50,14 @@ var optionsWithLatencyGenerator = new LatencyStrategyOptions
 };
 
 // To get notifications when a delay is injected
-var optionsOnBehaviorInjected = new LatencyStrategyOptions
+var optionsOnLatencyInjected = new LatencyStrategyOptions
 {
     Latency = TimeSpan.FromSeconds(30),
     Enabled = true,
     InjectionRate = 0.1,
-    OnLatency = static args =>
+    OnLatencyInjected = static args =>
     {
-        Console.WriteLine($"OnLatency, Latency: {args.Latency}, Operation: {args.Context.OperationKey}.");
+        Console.WriteLine($"OnLatencyInjected, Latency: {args.Latency}, Operation: {args.Context.OperationKey}.");
         return default;
     }
 };
@@ -97,11 +97,11 @@ var pipeline = new ResiliencePipelineBuilder()
 
 ## Defaults
 
-| Property           | Default Value | Description                                            |
-|--------------------|---------------|--------------------------------------------------------|
-| `Latency`          | `30 seconds`  | A `TimeSpan` indicating the delay to be injected.      |
-| `LatencyGenerator` | `null`        | Generates the latency to inject for a given execution. |
-| `OnLatency`        | `null`        | Action executed when latency is injected.              |
+| Property            | Default Value | Description                                            |
+|---------------------|---------------|--------------------------------------------------------|
+| `Latency`           | `30 seconds`  | A `TimeSpan` indicating the delay to be injected.      |
+| `LatencyGenerator`  | `null`        | Generates the latency to inject for a given execution. |
+| `OnLatencyInjected` | `null`        | Action executed when latency is injected.              |
 
 ## Diagrams
 
diff --git a/src/Polly.Core/PublicAPI.Unshipped.txt b/src/Polly.Core/PublicAPI.Unshipped.txt
@@ -55,13 +55,13 @@ Polly.Simmy.Latency.LatencyStrategyOptions.Latency.set -> void
 Polly.Simmy.Latency.LatencyStrategyOptions.LatencyGenerator.get -> System.Func<Polly.Simmy.Latency.LatencyGeneratorArguments, System.Threading.Tasks.ValueTask<System.TimeSpan>>?
 Polly.Simmy.Latency.LatencyStrategyOptions.LatencyGenerator.set -> void
 Polly.Simmy.Latency.LatencyStrategyOptions.LatencyStrategyOptions() -> void
-Polly.Simmy.Latency.LatencyStrategyOptions.OnLatency.get -> System.Func<Polly.Simmy.Latency.OnLatencyArguments, System.Threading.Tasks.ValueTask>?
-Polly.Simmy.Latency.LatencyStrategyOptions.OnLatency.set -> void
-Polly.Simmy.Latency.OnLatencyArguments
-Polly.Simmy.Latency.OnLatencyArguments.Context.get -> Polly.ResilienceContext!
-Polly.Simmy.Latency.OnLatencyArguments.Latency.get -> System.TimeSpan
-Polly.Simmy.Latency.OnLatencyArguments.OnLatencyArguments() -> void
-Polly.Simmy.Latency.OnLatencyArguments.OnLatencyArguments(Polly.ResilienceContext! context, System.TimeSpan latency) -> void
+Polly.Simmy.Latency.LatencyStrategyOptions.OnLatencyInjected.get -> System.Func<Polly.Simmy.Latency.OnLatencyInjectedArguments, System.Threading.Tasks.ValueTask>?
+Polly.Simmy.Latency.LatencyStrategyOptions.OnLatencyInjected.set -> void
+Polly.Simmy.Latency.OnLatencyInjectedArguments
+Polly.Simmy.Latency.OnLatencyInjectedArguments.Context.get -> Polly.ResilienceContext!
+Polly.Simmy.Latency.OnLatencyInjectedArguments.Latency.get -> System.TimeSpan
+Polly.Simmy.Latency.OnLatencyInjectedArguments.OnLatencyInjectedArguments() -> void
+Polly.Simmy.Latency.OnLatencyInjectedArguments.OnLatencyInjectedArguments(Polly.ResilienceContext! context, System.TimeSpan latency) -> void
 Polly.Simmy.LatencyPipelineBuilderExtensions
 Polly.Simmy.MonkeyStrategy
 Polly.Simmy.MonkeyStrategy.MonkeyStrategy(Polly.Simmy.MonkeyStrategyOptions! options) -> void
diff --git a/src/Polly.Core/Simmy/Behavior/BehaviorConstants.cs b/src/Polly.Core/Simmy/Behavior/BehaviorConstants.cs
@@ -2,5 +2,7 @@
 
 internal static class BehaviorConstants
 {
-    public const string OnBehaviorInjectedEvent = "OnBehaviorInjected";
+    public const string DefaultName = "Chaos.Behavior";
+
+    public const string OnBehaviorInjectedEvent = "Chaos.OnBehavior";
 }
diff --git a/src/Polly.Core/Simmy/Behavior/BehaviorStrategyOptions.cs b/src/Polly.Core/Simmy/Behavior/BehaviorStrategyOptions.cs
@@ -7,6 +7,11 @@ namespace Polly.Simmy.Behavior;
 /// </summary>
 public class BehaviorStrategyOptions : MonkeyStrategyOptions
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BehaviorStrategyOptions"/> class.
+    /// </summary>
+    public BehaviorStrategyOptions() => Name = BehaviorConstants.DefaultName;
+
     /// <summary>
     /// Gets or sets the delegate that's raised when the custom behavior is injected.
     /// </summary>
diff --git a/src/Polly.Core/Simmy/Fault/FaultConstants.cs b/src/Polly.Core/Simmy/Fault/FaultConstants.cs
@@ -2,5 +2,7 @@
 
 internal static class FaultConstants
 {
-    public const string OnFaultInjectedEvent = "OnFaultInjectedEvent";
+    public const string DefaultName = "Chaos.Fault";
+
+    public const string OnFaultInjectedEvent = "Chaos.OnFault";
 }
diff --git a/src/Polly.Core/Simmy/Fault/FaultStrategyOptions.cs b/src/Polly.Core/Simmy/Fault/FaultStrategyOptions.cs
@@ -7,6 +7,11 @@ namespace Polly.Simmy.Fault;
 /// </summary>
 public class FaultStrategyOptions : MonkeyStrategyOptions
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FaultStrategyOptions"/> class.
+    /// </summary>
+    public FaultStrategyOptions() => Name = FaultConstants.DefaultName;
+
     /// <summary>
     /// Gets or sets the delegate that's raised when the outcome is injected.
     /// </summary>
@@ -19,8 +24,7 @@ public class FaultStrategyOptions : MonkeyStrategyOptions
     /// Gets or sets the fault generator to be injected for a given execution.
     /// </summary>
     /// <remarks>
-    /// Defaults to <see langword="null"/>. Either <see cref="Fault"/> or this property is required.
-    /// When this property is <see langword="null"/> the <see cref="Fault"/> is used.
+    /// Defaults to <see langword="null"/>.
     /// </remarks>
     [Required]
     public Func<FaultGeneratorArguments, ValueTask<Exception?>>? FaultGenerator { get; set; } = default!;
diff --git a/src/Polly.Core/Simmy/Latency/LatencyChaosStrategy.cs b/src/Polly.Core/Simmy/Latency/LatencyChaosStrategy.cs
@@ -15,13 +15,13 @@ public LatencyChaosStrategy(
     {
         Latency = options.Latency;
         LatencyGenerator = options.LatencyGenerator is not null ? options.LatencyGenerator : (_) => new(options.Latency);
-        OnLatency = options.OnLatency;
+        OnLatencyInjected = options.OnLatencyInjected;
 
         _telemetry = telemetry;
         _timeProvider = timeProvider;
     }
 
-    public Func<OnLatencyArguments, ValueTask>? OnLatency { get; }
+    public Func<OnLatencyInjectedArguments, ValueTask>? OnLatencyInjected { get; }
 
     public Func<LatencyGeneratorArguments, ValueTask<TimeSpan>> LatencyGenerator { get; }
 
@@ -43,14 +43,14 @@ protected internal override async ValueTask<Outcome<TResult>> ExecuteCore<TResul
                     return await StrategyHelper.ExecuteCallbackSafeAsync(callback, context, state).ConfigureAwait(context.ContinueOnCapturedContext);
                 }
 
-                var args = new OnLatencyArguments(context, latency);
-                _telemetry.Report(new(ResilienceEventSeverity.Information, LatencyConstants.OnLatencyEvent), context, args);
+                var args = new OnLatencyInjectedArguments(context, latency);
+                _telemetry.Report(new(ResilienceEventSeverity.Information, LatencyConstants.OnLatencyInjectedEvent), context, args);
 
                 await _timeProvider.DelayAsync(latency, context).ConfigureAwait(context.ContinueOnCapturedContext);
 
-                if (OnLatency is not null)
+                if (OnLatencyInjected is not null)
                 {
-                    await OnLatency(args).ConfigureAwait(context.ContinueOnCapturedContext);
+                    await OnLatencyInjected(args).ConfigureAwait(context.ContinueOnCapturedContext);
                 }
             }
 
diff --git a/src/Polly.Core/Simmy/Latency/LatencyConstants.cs b/src/Polly.Core/Simmy/Latency/LatencyConstants.cs
@@ -2,7 +2,9 @@
 
 internal static class LatencyConstants
 {
-    public const string OnLatencyEvent = "OnLatency";
+    public const string DefaultName = "Chaos.Latency";
+
+    public const string OnLatencyInjectedEvent = "Chaos.OnLatency";
 
     public static readonly TimeSpan DefaultLatency = TimeSpan.FromSeconds(30);
 }
diff --git a/src/Polly.Core/Simmy/Latency/LatencyStrategyOptions.cs b/src/Polly.Core/Simmy/Latency/LatencyStrategyOptions.cs
@@ -7,13 +7,18 @@
 /// </summary>
 public class LatencyStrategyOptions : MonkeyStrategyOptions
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="LatencyStrategyOptions"/> class.
+    /// </summary>
+    public LatencyStrategyOptions() => Name = LatencyConstants.DefaultName;
+
     /// <summary>
     /// Gets or sets the delegate that's raised when a delay occurs.
     /// </summary>
     /// <remarks>
     /// Defaults to <see langword="null"/>.
     /// </remarks>
-    public Func<OnLatencyArguments, ValueTask>? OnLatency { get; set; }
+    public Func<OnLatencyInjectedArguments, ValueTask>? OnLatencyInjected { get; set; }
 
     /// <summary>
     /// Gets or sets the latency generator that generates the delay for a given execution.
diff --git a/src/Polly.Core/Simmy/Latency/OnLatencyInjectedArguments.cs b/src/Polly.Core/Simmy/Latency/OnLatencyInjectedArguments.cs
@@ -5,14 +5,14 @@
 /// <summary>
 /// Arguments used by the latency chaos strategy to notify that a delayed occurred.
 /// </summary>
-public readonly struct OnLatencyArguments
+public readonly struct OnLatencyInjectedArguments
 {
     /// <summary>
-    /// Initializes a new instance of the <see cref="OnLatencyArguments"/> struct.
+    /// Initializes a new instance of the <see cref="OnLatencyInjectedArguments"/> struct.
     /// </summary>
     /// <param name="context">The context associated with the execution of a user-provided callback.</param>
     /// <param name="latency">The latency that was injected.</param>
-    public OnLatencyArguments(ResilienceContext context, TimeSpan latency)
+    public OnLatencyInjectedArguments(ResilienceContext context, TimeSpan latency)
     {
         Context = context;
         Latency = latency;
diff --git a/src/Polly.Core/Simmy/Outcomes/OutcomeConstants.cs b/src/Polly.Core/Simmy/Outcomes/OutcomeConstants.cs
@@ -2,5 +2,7 @@
 
 internal static class OutcomeConstants
 {
-    public const string OnOutcomeInjectedEvent = "OnOutcomeInjected";
+    public const string DefaultName = "Chaos.Outcome";
+
+    public const string OnOutcomeInjectedEvent = "Chaos.OnOutcome";
 }
diff --git a/src/Polly.Core/Simmy/Outcomes/OutcomeStrategyOptions.cs b/src/Polly.Core/Simmy/Outcomes/OutcomeStrategyOptions.cs
@@ -8,6 +8,11 @@ namespace Polly.Simmy.Outcomes;
 /// <typeparam name="TResult">The type of the outcome that was injected.</typeparam>
 public class OutcomeStrategyOptions<TResult> : MonkeyStrategyOptions
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="OutcomeStrategyOptions{TResult}"/> class.
+    /// </summary>
+    public OutcomeStrategyOptions() => Name = OutcomeConstants.DefaultName;
+
     /// <summary>
     /// Gets or sets the delegate that's invoked when the outcome is injected.
     /// </summary>
diff --git a/src/Snippets/Docs/Chaos.Latency.cs b/src/Snippets/Docs/Chaos.Latency.cs
@@ -44,14 +44,14 @@ public static void LatencyUsage()
         };
 
         // To get notifications when a delay is injected
-        var optionsOnBehaviorInjected = new LatencyStrategyOptions
+        var optionsOnLatencyInjected = new LatencyStrategyOptions
         {
             Latency = TimeSpan.FromSeconds(30),
             Enabled = true,
             InjectionRate = 0.1,
-            OnLatency = static args =>
+            OnLatencyInjected = static args =>
             {
-                Console.WriteLine($"OnLatency, Latency: {args.Latency}, Operation: {args.Context.OperationKey}.");
+                Console.WriteLine($"OnLatencyInjected, Latency: {args.Latency}, Operation: {args.Context.OperationKey}.");
                 return default;
             }
         };
diff --git a/test/Polly.Core.Tests/Simmy/Behavior/BehaviorConstantsTests.cs b/test/Polly.Core.Tests/Simmy/Behavior/BehaviorConstantsTests.cs
@@ -7,6 +7,7 @@ public class BehaviorConstantsTests
     [Fact]
     public void EnsureDefaults()
     {
-        BehaviorConstants.OnBehaviorInjectedEvent.Should().Be("OnBehaviorInjected");
+        BehaviorConstants.DefaultName.Should().Be("Chaos.Behavior");
+        BehaviorConstants.OnBehaviorInjectedEvent.Should().Be("Chaos.OnBehavior");
     }
 }
diff --git a/test/Polly.Core.Tests/Simmy/Fault/FaultConstantsTests.cs b/test/Polly.Core.Tests/Simmy/Fault/FaultConstantsTests.cs
@@ -7,6 +7,7 @@ public class FaultConstantsTests
     [Fact]
     public void EnsureDefaults()
     {
-        FaultConstants.OnFaultInjectedEvent.Should().Be("OnFaultInjectedEvent");
+        FaultConstants.DefaultName.Should().Be("Chaos.Fault");
+        FaultConstants.OnFaultInjectedEvent.Should().Be("Chaos.OnFault");
     }
 }
diff --git a/test/Polly.Core.Tests/Simmy/Latency/LatencyChaosStrategyTests.cs b/test/Polly.Core.Tests/Simmy/Latency/LatencyChaosStrategyTests.cs
@@ -32,7 +32,7 @@ public async Task Given_enabled_and_randomly_within_threshold_should_inject_late
         _options.Enabled = true;
         _options.Latency = _delay;
         _options.Randomizer = () => 0.5;
-        _options.OnLatency = args =>
+        _options.OnLatencyInjected = args =>
         {
             args.Context.Should().NotBeNull();
             args.Context.CancellationToken.IsCancellationRequested.Should().BeFalse();
@@ -51,7 +51,7 @@ public async Task Given_enabled_and_randomly_within_threshold_should_inject_late
         (after - before).Should().Be(_delay);
 
         _args.Should().HaveCount(1);
-        _args[0].Arguments.Should().BeOfType<OnLatencyArguments>();
+        _args[0].Arguments.Should().BeOfType<OnLatencyInjectedArguments>();
         onLatencyExecuted.Should().BeTrue();
     }
 
@@ -110,7 +110,7 @@ public async Task Given_latency_is_negative_should_not_inject_latency(double lat
         _options.Latency = TimeSpan.FromSeconds(latency);
         _options.Randomizer = () => 0.5;
 
-        _options.OnLatency = args =>
+        _options.OnLatencyInjected = args =>
         {
             args.Context.Should().NotBeNull();
             args.Context.CancellationToken.IsCancellationRequested.Should().BeFalse();
diff --git a/test/Polly.Core.Tests/Simmy/Latency/LatencyConstantsTests.cs b/test/Polly.Core.Tests/Simmy/Latency/LatencyConstantsTests.cs
@@ -7,7 +7,8 @@ public class LatencyConstantsTests
     [Fact]
     public void EnsureDefaults()
     {
-        LatencyConstants.OnLatencyEvent.Should().Be("OnLatency");
+        LatencyConstants.DefaultName.Should().Be("Chaos.Latency");
+        LatencyConstants.OnLatencyInjectedEvent.Should().Be("Chaos.OnLatency");
         LatencyConstants.DefaultLatency.Should().Be(TimeSpan.FromSeconds(30));
     }
 }
diff --git a/test/Polly.Core.Tests/Simmy/Latency/LatencyStrategyOptionsTests.cs b/test/Polly.Core.Tests/Simmy/Latency/LatencyStrategyOptionsTests.cs
@@ -16,6 +16,6 @@ public void Ctor_Ok()
         sut.InjectionRateGenerator.Should().BeNull();
         sut.Latency.Should().Be(LatencyConstants.DefaultLatency);
         sut.LatencyGenerator.Should().BeNull();
-        sut.OnLatency.Should().BeNull();
+        sut.OnLatencyInjected.Should().BeNull();
     }
 }
diff --git a/test/Polly.Core.Tests/Simmy/Latency/OnLatencyInjectedArgumentsTests.cs b/test/Polly.Core.Tests/Simmy/Latency/OnLatencyInjectedArgumentsTests.cs
@@ -2,12 +2,12 @@
 
 namespace Polly.Core.Tests.Simmy.Latency;
 
-public class OnLatencyArgumentsTests
+public class OnLatencyInjectedArgumentsTests
 {
     [Fact]
     public void Ctor_Ok()
     {
-        var args = new OnLatencyArguments(ResilienceContextPool.Shared.Get(), TimeSpan.FromSeconds(10));
+        var args = new OnLatencyInjectedArguments(ResilienceContextPool.Shared.Get(), TimeSpan.FromSeconds(10));
         args.Context.Should().NotBeNull();
         args.Latency.Should().Be(TimeSpan.FromSeconds(10));
     }
diff --git a/test/Polly.Core.Tests/Simmy/Outcomes/OutcomeConstantsTests.cs b/test/Polly.Core.Tests/Simmy/Outcomes/OutcomeConstantsTests.cs
@@ -7,6 +7,7 @@ public class OutcomeConstantsTests
     [Fact]
     public void EnsureDefaults()
     {
-        OutcomeConstants.OnOutcomeInjectedEvent.Should().Be("OnOutcomeInjected");
+        OutcomeConstants.DefaultName.Should().Be("Chaos.Outcome");
+        OutcomeConstants.OnOutcomeInjectedEvent.Should().Be("Chaos.OnOutcome");
     }
 }

Original file line number	Diff line number	Diff line change
`@@ -2,5 +2,7 @@`
`2`	`2`
`3`	`3`	`internal static class BehaviorConstants`
`4`	`4`	`{`
`5`		`- public const string OnBehaviorInjectedEvent = "OnBehaviorInjected";`
	`5`	`+ public const string DefaultName = "Chaos.Behavior";`
	`6`	`+`
	`7`	`+ public const string OnBehaviorInjectedEvent = "Chaos.OnBehavior";`
`6`	`8`	`}`
Original file line number	Diff line number	Diff line change
`@@ -2,5 +2,7 @@`
`2`	`2`
`3`	`3`	`internal static class FaultConstants`
`4`	`4`	`{`
`5`		`- public const string OnFaultInjectedEvent = "OnFaultInjectedEvent";`
	`5`	`+ public const string DefaultName = "Chaos.Fault";`
	`6`	`+`
	`7`	`+ public const string OnFaultInjectedEvent = "Chaos.OnFault";`
`6`	`8`	`}`
Original file line number	Diff line number	Diff line change
`@@ -15,13 +15,13 @@ public LatencyChaosStrategy(`
`15`	`15`	`{`
`16`	`16`	`Latency = options.Latency;`
`17`	`17`	`LatencyGenerator = options.LatencyGenerator is not null ? options.LatencyGenerator : (_) => new(options.Latency);`
`18`		`- OnLatency = options.OnLatency;`
	`18`	`+ OnLatencyInjected = options.OnLatencyInjected;`
`19`	`19`
`20`	`20`	`_telemetry = telemetry;`
`21`	`21`	`_timeProvider = timeProvider;`
`22`	`22`	`}`
`23`	`23`
`24`		`- public Func<OnLatencyArguments, ValueTask>? OnLatency { get; }`
	`24`	`+ public Func<OnLatencyInjectedArguments, ValueTask>? OnLatencyInjected { get; }`
`25`	`25`
`26`	`26`	`public Func<LatencyGeneratorArguments, ValueTask<TimeSpan>> LatencyGenerator { get; }`
`27`	`27`
`@@ -43,14 +43,14 @@ protected internal override async ValueTask<Outcome<TResult>> ExecuteCore<TResul`
`43`	`43`	`return await StrategyHelper.ExecuteCallbackSafeAsync(callback, context, state).ConfigureAwait(context.ContinueOnCapturedContext);`
`44`	`44`	`}`
`45`	`45`
`46`		`- var args = new OnLatencyArguments(context, latency);`
`47`		`- _telemetry.Report(new(ResilienceEventSeverity.Information, LatencyConstants.OnLatencyEvent), context, args);`
	`46`	`+ var args = new OnLatencyInjectedArguments(context, latency);`
	`47`	`+ _telemetry.Report(new(ResilienceEventSeverity.Information, LatencyConstants.OnLatencyInjectedEvent), context, args);`
`48`	`48`
`49`	`49`	`await _timeProvider.DelayAsync(latency, context).ConfigureAwait(context.ContinueOnCapturedContext);`
`50`	`50`
`51`		`- if (OnLatency is not null)`
	`51`	`+ if (OnLatencyInjected is not null)`
`52`	`52`	`{`
`53`		`- await OnLatency(args).ConfigureAwait(context.ContinueOnCapturedContext);`
	`53`	`+ await OnLatencyInjected(args).ConfigureAwait(context.ContinueOnCapturedContext);`
`54`	`54`	`}`
`55`	`55`	`}`
`56`	`56`
Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,9 @@`
`2`	`2`
`3`	`3`	`internal static class LatencyConstants`
`4`	`4`	`{`
`5`		`- public const string OnLatencyEvent = "OnLatency";`
	`5`	`+ public const string DefaultName = "Chaos.Latency";`
	`6`	`+`
	`7`	`+ public const string OnLatencyInjectedEvent = "Chaos.OnLatency";`
`6`	`8`
`7`	`9`	`public static readonly TimeSpan DefaultLatency = TimeSpan.FromSeconds(30);`
`8`	`10`	`}`