feat(examples/feature-flags): add FeatureFlags sample with policies and batch scenarios

rian-be · rian-be · commit 663c4b14ee3f · 2026-01-31T03:43:54.000+01:00
- Added FeatureFlags example project wired with Mutators engine
- Implemented feature flag mutations:
  - EnableFeatureMutation
  - DisableFeatureMutation
- Added domain policies:
  - BusinessHoursPolicy (high-risk changes only during business hours)
  - RequireTwoManApprovalPolicy for critical feature flags
- Introduced execution scenarios:
  - EnableNewCheckoutScenario (single mutation)
  - DisableLegacyCheckoutScenario (approval-gated mutation)
  - BatchFeatureToggleScenario (mixed batch execution)
- Demonstrated:
  - User and system MutationContext usage
  - Correlation IDs and metadata-based approvals
  - Policy blocking and decision reporting
  - Batch execution with final state aggregation
  - Mutation history logging and metrics/statistics output
- Added immutable FeatureFlagsState domain model
- Registered FeatureFlags project in solution structure
diff --git a/ModularityKit.Mutator.slnx b/ModularityKit.Mutator.slnx
@@ -1,6 +1,7 @@
 <Solution>
   <Folder Name="/Polygon/">
     <Project Path="Polygon/BillingQuotas/BillingQuotas.csproj" />
+    <Project Path="Polygon/FeatureFlags/FeatureFlags.csproj" />
   </Folder>
   <Project Path="ModularityKit.Mutator/ModularityKit.Mutator.csproj" />
 </Solution>
diff --git a/Polygon/BillingQuotas/BillingQuotas.csproj b/Polygon/BillingQuotas/BillingQuotas.csproj
@@ -7,4 +7,12 @@
         <Nullable>enable</Nullable>
     </PropertyGroup>
 
+    <ItemGroup>
+      <ProjectReference Include="..\..\ModularityKit.Mutator\ModularityKit.Mutator.csproj" />
+    </ItemGroup>
+
+    <ItemGroup>
+      <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.2" />
+    </ItemGroup>
+
 </Project>
diff --git a/Polygon/BillingQuotas/Mutations/ResetQuotaMutation.cs b/Polygon/BillingQuotas/Mutations/ResetQuotaMutation.cs
@@ -4,6 +4,7 @@
 using ModularityKit.Mutator.Abstractions.Engine;
 using ModularityKit.Mutator.Abstractions.Intent;
 using ModularityKit.Mutator.Abstractions.Results;
+using ValidationResult = ModularityKit.Mutator.Abstractions.Results.ValidationResult;
 
 namespace BillingQuotas.Mutations;
 
diff --git a/Polygon/BillingQuotas/Program.cs b/Polygon/BillingQuotas/Program.cs
@@ -2,6 +2,7 @@
 using Microsoft.Extensions.DependencyInjection;
 using ModularityKit.Mutator.Abstractions;
 using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Runtime;
 
 namespace BillingQuotas;
 
diff --git a/Polygon/FeatureFlags/FeatureFlags.csproj b/Polygon/FeatureFlags/FeatureFlags.csproj
@@ -0,0 +1,18 @@
+﻿<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <OutputType>Exe</OutputType>
+        <TargetFramework>net10.0</TargetFramework>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <Nullable>enable</Nullable>
+    </PropertyGroup>
+
+    <ItemGroup>
+      <ProjectReference Include="..\..\ModularityKit.Mutator\ModularityKit.Mutator.csproj" />
+    </ItemGroup>
+
+    <ItemGroup>
+      <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="10.0.2" />
+    </ItemGroup>
+
+</Project>
diff --git a/Polygon/FeatureFlags/Mutations/DisableFeatureMutation.cs b/Polygon/FeatureFlags/Mutations/DisableFeatureMutation.cs
@@ -0,0 +1,46 @@
+using FeatureFlags.State;
+using ModularityKit.Mutator.Abstractions.Changes;
+using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Intent;
+using ModularityKit.Mutator.Abstractions.Results;
+
+namespace FeatureFlags.Mutations;
+
+/// <summary>
+/// Mutation that disables a feature flag in the current <see cref="FeatureFlagsState"/>.
+/// </summary>
+internal sealed record DisableFeatureMutation(string FeatureName, MutationContext Context) : IMutation<FeatureFlagsState>
+{
+    public MutationIntent Intent { get; } = new()
+    {
+        OperationName = "DisableFeature",
+        Category = "Configuration",
+        RiskLevel = MutationRiskLevel.High,
+        Description = "Disables a feature flag."
+    };
+
+    public MutationResult<FeatureFlagsState> Apply(FeatureFlagsState state)
+    {
+        var newFlags = new Dictionary<string, bool>(state.Flags);
+        if (newFlags.ContainsKey(FeatureName))
+            newFlags[FeatureName] = false;
+        
+        var newState = state with { Flags = newFlags };
+        var changes = ChangeSet.Single(StateChange.Modified($"Flags.{FeatureName}", true, false));
+        return MutationResult<FeatureFlagsState>.Success(newState, changes);
+    }
+
+    public ValidationResult Validate(FeatureFlagsState state)
+    {
+        var result = new ValidationResult();
+        
+        if (string.IsNullOrEmpty(FeatureName))
+            result.AddError("FeatureName", "Feature name cannot be empty");
+        if (!state.Flags.ContainsKey(FeatureName))
+            result.AddError("FeatureName", $"Feature '{FeatureName}' does not exist");
+        return result;
+    }
+
+    public MutationResult<FeatureFlagsState> Simulate(FeatureFlagsState state) => Apply(state);
+}
diff --git a/Polygon/FeatureFlags/Mutations/EnableFeatureMutation.cs b/Polygon/FeatureFlags/Mutations/EnableFeatureMutation.cs
@@ -0,0 +1,55 @@
+using FeatureFlags.State;
+using ModularityKit.Mutator.Abstractions.Changes;
+using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Intent;
+using ModularityKit.Mutator.Abstractions.Results;
+
+namespace FeatureFlags.Mutations;
+
+/// <summary>
+/// Mutation that enables feature flag in the current <see cref="FeatureFlagsState"/>.
+/// </summary>
+internal sealed record EnableFeatureMutation(string FeatureName, MutationContext Context) : IMutation<FeatureFlagsState>
+{
+    public MutationIntent Intent { get; } = new()
+    {
+        OperationName = "EnableFeature",
+        Category = "Security",
+        Tags = new HashSet<string> { "auth" },
+        RiskLevel = MutationRiskLevel.High,
+        Description = "Enables a feature flag."
+    };
+
+    public MutationResult<FeatureFlagsState> Apply(FeatureFlagsState state)
+    {
+        if (state.Flags.TryGetValue(FeatureName, out var oldValue) && oldValue)
+            return MutationResult<FeatureFlagsState>.Success(state, ChangeSet.Empty);
+
+        var newFlags = new Dictionary<string, bool>(state.Flags)
+        {
+            [FeatureName] = true
+        };
+        var newState = state with { Flags = newFlags };
+        var changes = ChangeSet.Single(
+            StateChange.Modified($"Flags.{FeatureName}", oldValue, true)
+        );
+        return MutationResult<FeatureFlagsState>.Success(newState, changes);
+    }
+
+    public ValidationResult Validate(FeatureFlagsState state)
+    {
+        var result = new ValidationResult();
+        if (string.IsNullOrEmpty(FeatureName))
+        {
+            result.AddError("FeatureName", "Feature name cannot be empty");
+        }
+        else if (!state.Flags.ContainsKey(FeatureName))
+        {
+            result.AddError("FeatureName", $"Feature '{FeatureName}' does not exist");
+        }
+        return result;
+    }
+
+    public MutationResult<FeatureFlagsState> Simulate(FeatureFlagsState state) => Apply(state);
+}
diff --git a/Polygon/FeatureFlags/Policies/BusinessHoursPolicy.cs b/Polygon/FeatureFlags/Policies/BusinessHoursPolicy.cs
@@ -0,0 +1,30 @@
+using FeatureFlags.State;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Intent;
+using ModularityKit.Mutator.Abstractions.Policies;
+
+namespace FeatureFlags.Policies;
+
+/// <summary>
+/// Policy that restricts high risk mutations to business hours (9:00-17:00 UTC).
+/// </summary>
+public class BusinessHoursPolicy : IMutationPolicy<FeatureFlagsState>
+{
+    public string Name => "BusinessHoursPolicy";
+    public int Priority => 100;
+    public string Description => "High-risk mutations are only allowed during business hours (9:00-17:00 UTC).";
+
+    public PolicyDecision Evaluate(IMutation<FeatureFlagsState> mutation, FeatureFlagsState state)
+    {
+        if (mutation.Intent.RiskLevel < MutationRiskLevel.High) return PolicyDecision.Allow(Name);
+        var hour = DateTime.UtcNow.Hour;
+
+        if (hour is < 9 or >= 17)
+        {
+            return PolicyDecision.Deny(
+                "High-risk changes are only allowed during business hours (9-17 UTC).",
+                Name);
+        }
+        return PolicyDecision.Allow(Name);
+    }
+}
diff --git a/Polygon/FeatureFlags/Policies/RequireTwoManApprovalPolicy.cs b/Polygon/FeatureFlags/Policies/RequireTwoManApprovalPolicy.cs
@@ -0,0 +1,43 @@
+using FeatureFlags.Mutations;
+using FeatureFlags.State;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Policies;
+
+namespace FeatureFlags.Policies;
+
+/// <summary>
+/// Policy that requires two man approval for disabling critical feature flags.
+/// </summary>
+public sealed class RequireTwoManApprovalPolicy : IMutationPolicy<FeatureFlagsState>
+{
+    public string Name => nameof(RequireTwoManApprovalPolicy);
+    public int Priority => 100;
+    public string Description => "Description";
+    
+    private readonly HashSet<string> _criticalFlags = ["NewCheckout", "BetaFeatures"];
+
+    public PolicyDecision Evaluate(IMutation<FeatureFlagsState> mutation, FeatureFlagsState state)
+    {
+        if (mutation is not DisableFeatureMutation disable || !_criticalFlags.Contains(disable.FeatureName))
+            return PolicyDecision.Allow(Name);
+
+        if (!mutation.Context.Metadata.TryGetValue("approvedBy", out var approvedObj))
+            return PolicyDecision.Deny("Critical feature requires two-man approval (none provided)", Name);
+
+        var approvedBy = (approvedObj switch
+        {
+            string s => s.Split(',').Select(x => x.Trim()).Where(x => !string.IsNullOrEmpty(x)),
+            IEnumerable<string> arr => arr,
+            _ => (IEnumerable<string>)[]
+        })
+        .Where(x => !string.Equals(x, mutation.Context.ActorId, StringComparison.OrdinalIgnoreCase))
+        .Distinct(StringComparer.OrdinalIgnoreCase)
+        .ToArray();
+
+        return approvedBy.Length switch
+        {
+            < 2 => PolicyDecision.Deny("Critical feature requires at least two distinct approvers (excluding the actor)", Name),
+            _ => PolicyDecision.Allow(Name)
+        };
+    }
+}
diff --git a/Polygon/FeatureFlags/Program.cs b/Polygon/FeatureFlags/Program.cs
@@ -0,0 +1,44 @@
+﻿using FeatureFlags.Policies;
+using Microsoft.Extensions.DependencyInjection;
+using ModularityKit.Mutator.Abstractions;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Runtime;
+using ModularityKit.Mutator.Runtime.Loggers;
+
+namespace FeatureFlags;
+
+internal static class Program
+{
+    private static async Task Main()
+    {
+        var services = new ServiceCollection();
+        services.AddMutators(MutationEngineOptions.Strict, addDefaultLoggingInterceptor: true);
+       
+        var provider = services.BuildServiceProvider();
+        var engine = provider.GetRequiredService<IMutationEngine>();
+        
+        //engine.RegisterPolicy(new BusinessHoursPolicy());
+        engine.RegisterPolicy(new RequireTwoManApprovalPolicy());
+
+        Console.WriteLine("=== ModularityKit.Mutators - Complete Example ===\n");
+        
+        await Scenarios.EnableNewCheckoutScenario.Run(engine);
+        await Scenarios.DisableLegacyCheckoutScenario.Run(engine);
+        await Scenarios.BatchFeatureToggleScenario.Run(engine);
+
+        var history = await engine.GetHistoryAsync(stateId: "EnableNewCheckout");
+        MutationHistoryLogger.LogHistory(history);
+        
+        Console.WriteLine("\n METRICS & STATISTICS");
+
+        var stats = await engine.GetStatisticsAsync();
+
+        Console.WriteLine($"\n Mutation Statistics:");
+        Console.WriteLine($"  Total executed: {stats.TotalExecuted}");
+
+        Console.WriteLine($"\n Performance Metrics:");
+        Console.WriteLine($"  Average execution time: {stats.AverageExecutionTime.TotalMilliseconds:F2} ms");
+        Console.WriteLine($"  Median execution time: {stats.MedianExecutionTime.TotalMilliseconds:F2} ms");
+        Console.WriteLine($"  P95 execution time: {stats.P95ExecutionTime.TotalMilliseconds:F2} ms");
+    }
+}
diff --git a/Polygon/FeatureFlags/Scenarios/BatchFeatureToggleScenario.cs b/Polygon/FeatureFlags/Scenarios/BatchFeatureToggleScenario.cs
@@ -0,0 +1,108 @@
+using FeatureFlags.Mutations;
+using FeatureFlags.State;
+using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Results;
+using ModularityKit.Mutator.Runtime.Loggers;
+
+namespace FeatureFlags.Scenarios;
+
+/// <summary>
+/// BatchFeatureToggleScenario
+/// 
+/// Demonstrates batch execution of multiple feature flag mutations, both enabling and disabling features,
+/// using the <see cref="IMutation{TState}"/> and <see cref="IMutationEngine.ExecuteBatchAsync{TState}"/> abstractions.
+///
+/// This scenario exercises:
+/// 
+/// - Batch mutation execution with <see cref="IMutationEngine"/>
+/// - Enforcement of policies via <see cref="EnableFeatureMutation"/>
+/// - User level <see cref="DisableFeatureMutation"/> for correlation, auditing, and approvals
+/// - Logging of batch results using <see cref="MutationContext"/>
+/// - Handling multiple feature flags simultaneously, simulating real-world operations like releases or A/B tests
+/// 
+/// Key Steps:
+/// 1. Initialize <see cref="IMutationEngine.ExecuteBatchAsync{TState}"/> with example feature flags.
+/// 2. Construct a set of <see cref="IMutationEngine"/> and <see cref="BatchMutationResult{TState}.FinalState"/> instances,
+///    each with its own <see cref="BatchMutationResult{TState}"/>.
+/// 3. Execute the batch using <see cref="IMutationEngine"/>.
+/// 4. Log individual mutation results and policy decisions.
+/// 5. Update local state using <see cref="MutationContext"/>.
+/// 6. Output the final feature flag states.
+///
+/// Example Use Case:
+/// - Simultaneously enabling/disabling multiple features during release.
+/// - Performing controlled feature toggling for A/B testing or canary releases.
+/// - Ensuring auditability and policy compliance across multiple feature mutations.
+/// 
+/// Notes:
+/// - If any mutation is blocked by a policy, the other mutations in the batch are still executed.
+/// - Correlation IDs and metadata are used to track approvals and reasons for audit purposes.
+/// </summary>
+internal static class BatchFeatureToggleScenario
+{
+    internal static async Task Run(IMutationEngine engine)
+    {
+        Console.WriteLine("\n=== Batch Feature Toggle Scenario ===");
+
+        var state = new FeatureFlagsState
+        {
+            Flags = new Dictionary<string, bool>
+            {
+                ["LegacyCheckout"] = true,
+                ["NewCheckout"] = false,
+                ["DarkMode"] = false,
+                ["BetaFeatures"] = false
+            }
+        };
+
+        var mutations = new IMutation<FeatureFlagsState>[]
+        {
+            new EnableFeatureMutation(
+                "NewCheckout",
+                MutationContext.User("alice", "Alice", "Batch enable") 
+                    with { CorrelationId = "BatchToggle1" }
+            ),
+
+            new DisableFeatureMutation(
+                "LegacyCheckout",
+                MutationContext.User("bob", "Bob", "Batch disable") with
+                {
+                    CorrelationId = "BatchToggle2",
+                    Metadata = new Dictionary<string, object> { ["approvedBy"] = "alice,bob" }
+                }
+            ),
+
+            new EnableFeatureMutation(
+                "DarkMode",
+                MutationContext.User("carol", "Carol", "Batch enable") with { CorrelationId = "BatchToggle3" }
+            ),
+
+            new EnableFeatureMutation(
+                "BetaFeatures",
+                MutationContext.User("dave", "Dave", "Batch enable") with { CorrelationId = "BatchToggle4" }
+            ),
+        };
+
+        var batchResult = await engine.ExecuteBatchAsync(mutations, state);
+        MutationResultLogger.LogBatch(batchResult.Results);
+
+        Console.WriteLine($"Success: {batchResult.SuccessCount}, Failed: {batchResult.FailureCount}");
+        for (int i = 0; i < batchResult.Results.Count; i++)
+        {
+            var r = batchResult.Results[i];
+            var mutationType = mutations[i].GetType().Name;
+            Console.WriteLine($"{mutationType}: {(r.IsSuccess ? "✓ Applied" : "✗ Blocked")}");
+            if (!r.IsSuccess)
+            {
+                foreach (var dec in r.PolicyDecisions)
+                    Console.WriteLine($"  Policy: {dec.PolicyName} – {dec.Reason}");
+            }
+        }
+
+        // Poprawka: używamy FinalState z batchResult
+        state = batchResult.FinalState ?? state;
+
+        Console.WriteLine($"Final state: {string.Join(", ", state.Flags.Select(kv => $"{kv.Key}={kv.Value}"))}");
+    }
+}
diff --git a/Polygon/FeatureFlags/Scenarios/DisableLegacyCheckoutScenario.cs b/Polygon/FeatureFlags/Scenarios/DisableLegacyCheckoutScenario.cs
diff --git a/Polygon/FeatureFlags/Scenarios/EnableNewCheckoutScenario.cs b/Polygon/FeatureFlags/Scenarios/EnableNewCheckoutScenario.cs
diff --git a/Polygon/FeatureFlags/State/FeatureFlagsState.cs b/Polygon/FeatureFlags/State/FeatureFlagsState.cs
