Document outcome strategy anti-patterns

docs/chaos/outcome.md

@@ -149,7 +149,7 @@ new ResiliencePipelineBuilder<HttpResponseMessage>()
 ```
 <!-- endSnippet -->
 
-### Use delegates to generate faults
+### Use delegates to generate outcomes
 
 Delegates give you the most flexibility at the expense of slightly more complicated syntax. Delegates also support asynchronous outcome generation, if you ever need that possibility.
 
@@ -161,17 +161,151 @@ new ResiliencePipelineBuilder<HttpResponseMessage>()
         // The same behavior can be achieved with delegates
         OutcomeGenerator = args =>
         {
+            Outcome<HttpResponseMessage>? outcome = Random.Shared.Next(350) switch
+            {
+                < 100 => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.InternalServerError)),
+                < 150 => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.TooManyRequests)),
+                < 350 => Outcome.FromResult(CreateResultFromContext(args.Context)),
+                _ => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.OK))
+            };
+
+            return ValueTask.FromResult(outcome);
+        }
+    });
+```
+<!-- endSnippet -->
+
+## Anti-patterns
+
+### Injecting faults (exceptions)
+
+❌ DON'T
+
+Use outcome strategies to inject faults in advanced scenarios which you need to inject outcomes using delegates. This is an opinionated anti-pattern since you can consider an exception as a result/outcome, however, there might be undesired implications when doing so, one of them is the telemetry events, which might end up affecting your metrics as the `ChaosOutcomeStrategy` reports both result and exceptions in the same way, and this could pose a problem for instrumentation purposes since it's clearer looking for fault injected events to be 100% sure where/when exceptions were injected, rather than have them mixed in the same "bag".
+
+Also, you end up losing control of how/when to inject outcomes vs faults since this way does not allow you to control separately when to inject a fault vs an outcome.
+
+<!-- snippet: chaos-outcome-anti-pattern-generator-inject-fault -->
+```cs
+var pipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
+    .AddChaosOutcome(new ChaosOutcomeStrategyOptions<HttpResponseMessage>
+    {
+        InjectionRate = 0.5, // same injection rate for both fault and outcome
+        OutcomeGenerator = args =>
+        {   
             Outcome<HttpResponseMessage>? outcome = Random.Shared.Next(350) switch
             {
                 < 100 => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.InternalServerError)),
                 < 150 => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.TooManyRequests)),
                 < 250 => Outcome.FromResult(CreateResultFromContext(args.Context)),
-                < 350 => Outcome.FromException<HttpResponseMessage>(new TimeoutException()),
+                < 350 => Outcome.FromException<HttpResponseMessage>(new HttpRequestException("Chaos request exception.")), // ⚠️ Avoid this ⚠️ 
+                _ => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.OK))
+            };
+
+            return ValueTask.FromResult(outcome);
+        },
+        OnOutcomeInjected = static args =>
+        {
+            // You might have to put some logic here to determine what kind of output was injected. 😕
+            if (args.Outcome.Exception != null)
+            {
+                Console.WriteLine($"OnBehaviorInjected, Exception: {args.Outcome.Exception.Message}, Operation: {args.Context.OperationKey}.");
+            }
+            else
+            {
+                Console.WriteLine($"OnBehaviorInjected, Outcome: {args.Outcome.Result}, Operation: {args.Context.OperationKey}.");
+            }
+
+            return default;
+        }
+    })
+    .Build();
+```
+<!-- endSnippet -->
+
+✅ DO
+
+The previous approach is tempting since it looks more succinct, but use the fault chaos instead as the [`ChaosFaultStrategy`](fault.md) correctly tracks telemetry events effectively as faults not just as any other outcome, also by separating them you can control the injection rate and enable/disable them separately which gives you more control when it comes to injecting chaos dynamically and in a controlled manner.
+
+<!-- snippet: chaos-outcome-pattern-generator-inject-fault -->
+```cs
+var randomThreshold = Random.Shared.Next(350);
+var pipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
+    .AddChaosFault(new ChaosFaultStrategyOptions
+    {
+        InjectionRate = 0.1, // different injection rate for faults
+        EnabledGenerator = args => ValueTask.FromResult(ShouldEnableFaults(args.Context)), // different settings might apply to inject faults
+        FaultGenerator = args =>
+        {
+            Exception? exception = randomThreshold switch
+            {
+                >= 250 and < 350 => new HttpRequestException("Chaos request exception."),
                 _ => null
             };
 
+            return new ValueTask<Exception?>(exception);
+        },
+        OnFaultInjected = static args =>
+        {
+            Console.WriteLine($"OnFaultInjected, Exception: {args.Fault.Message}, Operation: {args.Context.OperationKey}.");
+            return default;
+        }
+    })
+    .AddChaosOutcome(new ChaosOutcomeStrategyOptions<HttpResponseMessage>
+    {
+        InjectionRate = 0.5, // different injection rate for outcomes
+        EnabledGenerator = args => ValueTask.FromResult(ShouldEnableOutcome(args.Context)), // different settings might apply to inject outcomes
+        OutcomeGenerator = args =>
+        {
+            Outcome<HttpResponseMessage>? outcome = randomThreshold switch
+            {
+                < 100 => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.InternalServerError)),
+                < 150 => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.TooManyRequests)),
+                < 250 => Outcome.FromResult(CreateResultFromContext(args.Context)),
+                _ => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.OK))
+            };
+
             return ValueTask.FromResult(outcome);
+        },
+        OnOutcomeInjected = static args =>
+        {
+            Console.WriteLine($"OnBehaviorInjected, Outcome: {args.Outcome.Result}, Operation: {args.Context.OperationKey}.");
+            return default;
         }
+    })
+    .Build();
+```
+<!-- endSnippet -->
+
+❌ DON'T
+
+Use outcome strategies to inject only faults, use the [`ChaosFaultStrategy`](fault.md) instead.
+
+<!-- snippet: chaos-outcome-anti-pattern-only-inject-fault -->
+```cs
+new ResiliencePipelineBuilder<HttpResponseMessage>()
+    .AddChaosOutcome(new ChaosOutcomeStrategyOptions<HttpResponseMessage>
+    {
+        OutcomeGenerator = new OutcomeGenerator<HttpResponseMessage>()
+            .AddException<HttpRequestException>(), // ⚠️ Avoid this ⚠️ 
     });
 ```
 <!-- endSnippet -->
+
+✅ DO
+
+Use fault strategies to properly inject the exception.
+
+<!-- snippet: chaos-outcome-pattern-only-inject-fault -->
+```cs
+new ResiliencePipelineBuilder<HttpResponseMessage>()
+    .AddChaosFault(new ChaosFaultStrategyOptions
+    {
+        FaultGenerator = new FaultGenerator()
+            .AddException<HttpRequestException>(),
+    });
+```
+<!-- endSnippet -->
+
+> [!NOTE]
+> Even though the outcome strategy is flexible enough to allow you to inject outcomes as well as exceptions without the need to chain a fault strategy in the pipeline, use your judgment when doing so because of the caveats and side effects explained before around the telemetry and injection control.

src/Snippets/Docs/Chaos.Outcome.cs

@@ -1,7 +1,8 @@
-using System.Net;
+using System.Net;
 using System.Net.Http;
 using Polly.Retry;
 using Polly.Simmy;
+using Polly.Simmy.Fault;
 using Polly.Simmy.Outcomes;
 
 namespace Snippets.Docs;
@@ -105,15 +106,138 @@ public static void OutcomeGeneratorDelegates()
                         < 150 => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.TooManyRequests)),
                         < 250 => Outcome.FromResult(CreateResultFromContext(args.Context)),
                         < 350 => Outcome.FromException<HttpResponseMessage>(new TimeoutException()),
+                        _ => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.OK))
+                    };
+
+                    return ValueTask.FromResult(outcome);
+                }
+            });
+
+        #endregion
+    }
+
+    public static void AntiPattern_GeneratorDelegateInjectFault()
+    {
+        #region chaos-outcome-anti-pattern-generator-inject-fault
+        var pipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
+            .AddChaosOutcome(new ChaosOutcomeStrategyOptions<HttpResponseMessage>
+            {
+                InjectionRate = 0.5, // same injection rate for both fault and outcome
+                OutcomeGenerator = args =>
+                {
+                    Outcome<HttpResponseMessage>? outcome = Random.Shared.Next(350) switch
+                    {
+                        < 100 => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.InternalServerError)),
+                        < 150 => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.TooManyRequests)),
+                        < 250 => Outcome.FromResult(CreateResultFromContext(args.Context)),
+                        < 350 => Outcome.FromException<HttpResponseMessage>(new HttpRequestException("Chaos request exception.")),
+                        _ => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.OK))
+                    };
+
+                    return ValueTask.FromResult(outcome);
+                },
+                OnOutcomeInjected = static args =>
+                {
+                    // You might have to put some logic here to determine what kind of output was injected. 😕
+                    if (args.Outcome.Exception != null)
+                    {
+                        Console.WriteLine($"OnBehaviorInjected, Exception: {args.Outcome.Exception.Message}, Operation: {args.Context.OperationKey}.");
+                    }
+                    else
+                    {
+                        Console.WriteLine($"OnBehaviorInjected, Outcome: {args.Outcome.Result}, Operation: {args.Context.OperationKey}.");
+                    }
+
+                    return default;
+                }
+            })
+            .Build();
+
+        #endregion
+    }
+
+    public static void Pattern_GeneratorDelegateInjectFaultAndOutcome()
+    {
+        #region chaos-outcome-pattern-generator-inject-fault
+        var randomThreshold = Random.Shared.Next(350);
+        var pipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
+            .AddChaosFault(new ChaosFaultStrategyOptions
+            {
+                InjectionRate = 0.1, // different injection rate for faults
+                EnabledGenerator = args => ValueTask.FromResult(ShouldEnableFaults(args.Context)), // different settings might apply to inject faults
+                FaultGenerator = args =>
+                {
+                    Exception? exception = randomThreshold switch
+                    {
+                        >= 250 and < 350 => new HttpRequestException("Chaos request exception."),
                         _ => null
                     };
 
+                    return new ValueTask<Exception?>(exception);
+                },
+                OnFaultInjected = static args =>
+                {
+                    Console.WriteLine($"OnFaultInjected, Exception: {args.Fault.Message}, Operation: {args.Context.OperationKey}.");
+                    return default;
+                }
+            })
+            .AddChaosOutcome(new ChaosOutcomeStrategyOptions<HttpResponseMessage>
+            {
+                InjectionRate = 0.5, // different injection rate for outcomes
+                EnabledGenerator = args => ValueTask.FromResult(ShouldEnableOutcome(args.Context)), // different settings might apply to inject outcomes
+                OutcomeGenerator = args =>
+                {
+                    Outcome<HttpResponseMessage>? outcome = randomThreshold switch
+                    {
+                        < 100 => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.InternalServerError)),
+                        < 150 => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.TooManyRequests)),
+                        < 250 => Outcome.FromResult(CreateResultFromContext(args.Context)),
+                        _ => Outcome.FromResult(new HttpResponseMessage(HttpStatusCode.OK))
+                    };
+
                     return ValueTask.FromResult(outcome);
+                },
+                OnOutcomeInjected = static args =>
+                {
+                    Console.WriteLine($"OnBehaviorInjected, Outcome: {args.Outcome.Result}, Operation: {args.Context.OperationKey}.");
+                    return default;
                 }
+            })
+            .Build();
+        #endregion
+    }
+
+    public static void AntiPattern_OnlyInjectFault()
+    {
+        #region chaos-outcome-anti-pattern-only-inject-fault
+
+        new ResiliencePipelineBuilder<HttpResponseMessage>()
+            .AddChaosOutcome(new ChaosOutcomeStrategyOptions<HttpResponseMessage>
+            {
+                OutcomeGenerator = new OutcomeGenerator<HttpResponseMessage>()
+                    .AddException<HttpRequestException>(),
             });
 
         #endregion
     }
 
+    public static void Pattern_OnlyInjectFault()
+    {
+        #region chaos-outcome-pattern-only-inject-fault
+
+        new ResiliencePipelineBuilder<HttpResponseMessage>()
+            .AddChaosFault(new ChaosFaultStrategyOptions
+            {
+                FaultGenerator = new FaultGenerator()
+                    .AddException<HttpRequestException>(),
+            });
+
+        #endregion
+    }
+
+    private static bool ShouldEnableFaults(ResilienceContext context) => true;
+
+    private static bool ShouldEnableOutcome(ResilienceContext context) => true;
+
     private static HttpResponseMessage CreateResultFromContext(ResilienceContext context) => new(HttpStatusCode.TooManyRequests);
 }