Add variants for feature flags (#250)

* in progress, add new classes for variants and define methods in featuremanager

* Revert "Revert "Add cancellation token parameter to async feature management interfaces. (#131)" (#139)"

This reverts commit e531863.

* Revert "Revert "Added default value for cancellation token in interfaces to keep existing usage possible. (#133)" (#138)"

This reverts commit 8f9a7e4.

* fix any conflicts left from adding cancellationToken back

* add in progress changes to allocation and featuredefinitionprovider

* add examples for testing

* fix adding new featuredefinition properties from featuremanagement definition

* progress adding getvariant logic classes

* continued

* remove repeated code in contextual targeting

* fix version of contextual filter

* more progress on getting the contextual allocator to work

* about to test getvariant

* add example to test

* add snapshot changes

* variant can be detected and retrieved from getvariantasync

* progress on allocation logic, add comments where consideration needed

* add use of optionsresolver for reference, todo work on isenabledasync between customer use and variant use

* All working except couple TODOs, need to add unit tests

* remove some comments, add null check where needed

* update todo comments

* fix line eols

* add unit test, in progress

* TODOs in progress, need to restructure featurevariantassigner design

* fix seed logic

* update comments, status logic

* remove unnecessary files for custom assigners, fix featuremanager methods and interfaces to match

* fix naming from allocator to assigner for classes and files

* cleanup extra methods, todo config section logic

* in progress adding configurationsection returned when using configurationvalue

* continuation of last commit

* working return for configvalue

* move logic to featuremanager for assigning

* remove unused assigner classes

* add new configurationsection to handle return for variant

* null error, in progress new configurationsection class

* fix old bug

* progress on unit tests

* more null check changes, test fixes

* reset examples changes

* Revert "Revert "Revert "Added default value for cancellation token in interfaces to keep existing usage possible. (#133)" (#138)""

This reverts commit d087e7b.

* Revert "Revert "Revert "Add cancellation token parameter to async feature management interfaces. (#131)" (#139)""

This reverts commit c1451d3.

* add comments for new classes

* fix comments for public classes again

* update comments, default values

* fix variantconfigurationsection, comments in definitionprovider

* fix using statements, null checks

* fix unit test failures with servicecollectionextensions

* add revisions: fix namepaces, add exceptions tests, combine percentage logic, fix comments, add cancellationtoken to new interface

* change context accessor logic

* fix comments for default variants

* PR revisions

* change class names, PR fixes

* fix edge case percentage targeting

* rename allocation classes, remove exceptions and add warning logs, prioritize inline value for variant config, more revisions

* refactor isenabled to remove boolean param

* change configurationvalue to IConfigurationSection instead of string

* fix enabledwithvariants logic

* PR revisions, fix logic in new methods from last commit

* set session managers last in flow

* make false explicit for status disabled or missing definition

* fix constructor default params, move session managers logic, pr revisions

* fix comment

* fix resolvedefaultvariant, isexternalinit error

* add back 3.1

* Apply suggestions from code review

Co-authored-by: Jimmy Campbell <jimmyca@microsoft.com>

* isexternalinit comments, remove resolvedefault helper

* remove binding, fix featuredefinitionprovider issues

* change to Debug.Assert from Assert

* update method name

* remove parseenum, add ConfigurationFields class

* test failing, fixed PR revisions

* fix invalid scenarios test

* simplify context in test

* remove unused using

* remove unused param

* Clarify how From and To bounds work in PercentileAllocation

Co-authored-by: Ross Grambo <rossgrambo@microsoft.com>

* fix error messages

* add feature name as default seed with allocation prefix

* Update src/Microsoft.FeatureManagement/FeatureManager.cs

Co-authored-by: Jimmy Campbell <jimmyca@microsoft.com>

---------

Co-authored-by: Jimmy Campbell <jimmyca@microsoft.com>
Co-authored-by: Ross Grambo <rossgrambo@microsoft.com>

Author: 3 people

examples/FeatureFlagDemo/appsettings.json

@@ -5,7 +5,7 @@
     }
   },
   "AllowedHosts": "*",
-  
+
   // Define feature flags in config file
   "FeatureManagement": {
 
@@ -36,7 +36,7 @@
         }
       ]
     },
-    "CustomViewData":  {
+    "CustomViewData": {
       "EnabledFor": [
         {
           "Name": "Browser",

src/Microsoft.FeatureManagement/Allocation/Allocation.cs

@@ -0,0 +1,43 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+using System.Collections.Generic;
+
+namespace Microsoft.FeatureManagement
+{
+    /// <summary>
+    /// The definition of how variants are allocated for a feature.
+    /// </summary>
+    public class Allocation
+    {
+        /// <summary>
+        /// The default variant used if the feature is enabled and no variant is assigned.
+        /// </summary>
+        public string DefaultWhenEnabled { get; set; }
+
+        /// <summary>
+        /// The default variant used if the feature is disabled.
+        /// </summary>
+        public string DefaultWhenDisabled { get; set; }
+
+        /// <summary>
+        /// Describes a mapping of user ids to variants.
+        /// </summary>
+        public IEnumerable<UserAllocation> User { get; set; }
+
+        /// <summary>
+        /// Describes a mapping of group names to variants.
+        /// </summary>
+        public IEnumerable<GroupAllocation> Group { get; set; }
+
+        /// <summary>
+        /// Allocates percentiles of user base to variants.
+        /// </summary>
+        public IEnumerable<PercentileAllocation> Percentile { get; set; }
+
+        /// <summary>
+        /// Maps users to the same percentile across multiple feature flags.
+        /// </summary>
+        public string Seed { get; set; }
+    }
+}

src/Microsoft.FeatureManagement/Allocation/GroupAllocation.cs

@@ -0,0 +1,24 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+
+using System.Collections.Generic;
+
+namespace Microsoft.FeatureManagement
+{
+    /// <summary>
+    /// The definition of a group allocation.
+    /// </summary>
+    public class GroupAllocation
+    {
+        /// <summary>
+        /// The name of the variant.
+        /// </summary>
+        public string Variant { get; set; }
+
+        /// <summary>
+        /// A list of groups that can be assigned this variant.
+        /// </summary>
+        public IEnumerable<string> Groups { get; set; }
+    }
+}

src/Microsoft.FeatureManagement/Allocation/PercentileAllocation.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+
+namespace Microsoft.FeatureManagement
+{
+    /// <summary>
+    /// The definition of a percentile allocation.
+    /// </summary>
+    public class PercentileAllocation
+    {
+        /// <summary>
+        /// The name of the variant.
+        /// </summary>
+        public string Variant { get; set; }
+
+        /// <summary>
+        /// The inclusive lower bound of the percentage to which the variant will be assigned.
+        /// </summary>
+        public double From { get; set; }
+
+        /// <summary>
+        /// The exclusive upper bound of the percentage to which the variant will be assigned.
+        /// </summary>
+        public double To { get; set; }
+    }
+}

src/Microsoft.FeatureManagement/Allocation/UserAllocation.cs

@@ -0,0 +1,24 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+
+using System.Collections.Generic;
+
+namespace Microsoft.FeatureManagement
+{
+    /// <summary>
+    /// The definition of a user allocation.
+    /// </summary>
+    public class UserAllocation
+    {
+        /// <summary>
+        /// The name of the variant.
+        /// </summary>
+        public string Variant { get; set; }
+
+        /// <summary>
+        /// A list of users that will be assigned this variant.
+        /// </summary>
+        public IEnumerable<string> Users { get; set; }
+    }
+}

src/Microsoft.FeatureManagement/ConfigurationFeatureDefinitionProvider.cs

@@ -6,6 +6,7 @@
 using System;
 using System.Collections.Concurrent;
 using System.Collections.Generic;
+using System.Diagnostics;
 using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
@@ -21,13 +22,13 @@ sealed class ConfigurationFeatureDefinitionProvider : IFeatureDefinitionProvider
         // IFeatureDefinitionProviderCacheable interface is only used to mark this provider as cacheable. This allows our test suite's
         // provider to be marked for caching as well.
 
-        private const string FeatureFiltersSectionName = "EnabledFor";
-        private const string RequirementTypeKeyword = "RequirementType";
         private readonly IConfiguration _configuration;
         private readonly ConcurrentDictionary<string, FeatureDefinition> _definitions;
         private IDisposable _changeSubscription;
         private int _stale = 0;
 
+        const string ParseValueErrorString = "Invalid setting '{0}' with value '{1}' for feature '{2}'.";
+
         public ConfigurationFeatureDefinitionProvider(IConfiguration configuration)
         {
             _configuration = configuration ?? throw new ArgumentNullException(nameof(configuration));
@@ -136,13 +137,19 @@ We support
 
             RequirementType requirementType = RequirementType.Any;
 
+            FeatureStatus featureStatus = FeatureStatus.Conditional;
+
+            Allocation allocation = null;
+
+            List<VariantDefinition> variants = null;
+
             var enabledFor = new List<FeatureFilterConfiguration>();
 
             string val = configurationSection.Value; // configuration[$"{featureName}"];
 
             if (string.IsNullOrEmpty(val))
             {
-                val = configurationSection[FeatureFiltersSectionName];
+                val = configurationSection[ConfigurationFields.FeatureFiltersSectionName];
             }
 
             if (!string.IsNullOrEmpty(val) && bool.TryParse(val, out bool result) && result)
@@ -160,57 +167,173 @@ We support
             }
             else
             {
-                string rawRequirementType = configurationSection[RequirementTypeKeyword];
+                string rawRequirementType = configurationSection[ConfigurationFields.RequirementType];
 
-                //
-                // If requirement type is specified, parse it and set the requirementType variable
-                if (!string.IsNullOrEmpty(rawRequirementType) && !Enum.TryParse(rawRequirementType, ignoreCase: true, out requirementType))
+                string rawFeatureStatus = configurationSection[ConfigurationFields.FeatureStatus];
+
+                if (!string.IsNullOrEmpty(rawRequirementType))
                 {
-                    throw new FeatureManagementException(
-                        FeatureManagementError.InvalidConfigurationSetting, 
-                        $"Invalid requirement type '{rawRequirementType}' for feature '{configurationSection.Key}'.");
+                    requirementType = ParseEnum<RequirementType>(configurationSection.Key, rawRequirementType, ConfigurationFields.RequirementType);
                 }
 
-                IEnumerable<IConfigurationSection> filterSections = configurationSection.GetSection(FeatureFiltersSectionName).GetChildren();
+                if (!string.IsNullOrEmpty(rawFeatureStatus))
+                {
+                    featureStatus = ParseEnum<FeatureStatus>(configurationSection.Key, rawFeatureStatus, ConfigurationFields.FeatureStatus);
+                }
+
+                IEnumerable<IConfigurationSection> filterSections = configurationSection.GetSection(ConfigurationFields.FeatureFiltersSectionName).GetChildren();
 
                 foreach (IConfigurationSection section in filterSections)
                 {
                     //
                     // Arrays in json such as "myKey": [ "some", "values" ]
                     // Are accessed through the configuration system by using the array index as the property name, e.g. "myKey": { "0": "some", "1": "values" }
-                    if (int.TryParse(section.Key, out int i) && !string.IsNullOrEmpty(section[nameof(FeatureFilterConfiguration.Name)]))
+                    if (int.TryParse(section.Key, out int _) && !string.IsNullOrEmpty(section[ConfigurationFields.NameKeyword]))
                     {
                         enabledFor.Add(new FeatureFilterConfiguration()
                         {
-                            Name = section[nameof(FeatureFilterConfiguration.Name)],
-                            Parameters = new ConfigurationWrapper(section.GetSection(nameof(FeatureFilterConfiguration.Parameters)))
+                            Name = section[ConfigurationFields.NameKeyword],
+                            Parameters = new ConfigurationWrapper(section.GetSection(ConfigurationFields.FeatureFilterConfigurationParameters))
                         });
                     }
                 }
+
+                IConfigurationSection allocationSection = configurationSection.GetSection(ConfigurationFields.AllocationSectionName);
+
+                if (allocationSection.Exists())
+                {
+                    allocation = new Allocation()
+                    {
+                        DefaultWhenDisabled = allocationSection[ConfigurationFields.AllocationDefaultWhenDisabled],
+                        DefaultWhenEnabled = allocationSection[ConfigurationFields.AllocationDefaultWhenEnabled],
+                        User = allocationSection.GetSection(ConfigurationFields.UserAllocationSectionName).GetChildren().Select(userAllocation =>
+                        {
+                            return new UserAllocation()
+                            {
+                                Variant = userAllocation[ConfigurationFields.AllocationVariantKeyword],
+                                Users = userAllocation.GetSection(ConfigurationFields.UserAllocationUsers).Get<IEnumerable<string>>()
+                            };
+                        }),
+                        Group = allocationSection.GetSection(ConfigurationFields.GroupAllocationSectionName).GetChildren().Select(groupAllocation =>
+                        {
+                            return new GroupAllocation()
+                            {
+                                Variant = groupAllocation[ConfigurationFields.AllocationVariantKeyword],
+                                Groups = groupAllocation.GetSection(ConfigurationFields.GroupAllocationGroups).Get<IEnumerable<string>>()
+                            };
+                        }),
+                        Percentile = allocationSection.GetSection(ConfigurationFields.PercentileAllocationSectionName).GetChildren().Select(percentileAllocation =>
+                        {
+                            double from = 0;
+
+                            double to = 0;
+
+                            string rawFrom = percentileAllocation[ConfigurationFields.PercentileAllocationFrom];
+
+                            string rawTo = percentileAllocation[ConfigurationFields.PercentileAllocationTo];
+
+                            if (!string.IsNullOrEmpty(rawFrom))
+                            {
+                                from = ParseDouble(configurationSection.Key, rawFrom, ConfigurationFields.PercentileAllocationFrom);
+                            }
+
+                            if (!string.IsNullOrEmpty(rawTo))
+                            {
+                                to = ParseDouble(configurationSection.Key, rawTo, ConfigurationFields.PercentileAllocationTo);
+                            }
+
+                            return new PercentileAllocation()
+                            {
+                                Variant = percentileAllocation[ConfigurationFields.AllocationVariantKeyword],
+                                From = from,
+                                To = to
+                            };
+                        }),
+                        Seed = allocationSection[ConfigurationFields.AllocationSeed]
+                    };
+                }
+
+                IEnumerable<IConfigurationSection> variantsSections = configurationSection.GetSection(ConfigurationFields.VariantsSectionName).GetChildren();
+                variants = new List<VariantDefinition>();
+
+                foreach (IConfigurationSection section in variantsSections)
+                {
+                    if (int.TryParse(section.Key, out int _) && !string.IsNullOrEmpty(section[ConfigurationFields.NameKeyword]))
+                    {
+                        StatusOverride statusOverride = StatusOverride.None;
+
+                        string rawStatusOverride = section[ConfigurationFields.VariantDefinitionStatusOverride];
+
+                        if (!string.IsNullOrEmpty(rawStatusOverride))
+                        {
+                            statusOverride = ParseEnum<StatusOverride>(configurationSection.Key, rawStatusOverride, ConfigurationFields.VariantDefinitionStatusOverride);
+                        }
+
+                        VariantDefinition variant = new VariantDefinition()
+                        {
+                            Name = section[ConfigurationFields.NameKeyword],
+                            ConfigurationValue = section.GetSection(ConfigurationFields.VariantDefinitionConfigurationValue),
+                            ConfigurationReference = section[ConfigurationFields.VariantDefinitionConfigurationReference],
+                            StatusOverride = statusOverride
+                        };
+
+                        variants.Add(variant);
+                    }
+                }
             }
 
             return new FeatureDefinition()
             {
                 Name = configurationSection.Key,
                 EnabledFor = enabledFor,
-                RequirementType = requirementType
+                RequirementType = requirementType,
+                Status = featureStatus,
+                Allocation = allocation,
+                Variants = variants
             };
         }
 
         private IEnumerable<IConfigurationSection> GetFeatureDefinitionSections()
         {
-            const string FeatureManagementSectionName = "FeatureManagement";
-
-            if (_configuration.GetChildren().Any(s => s.Key.Equals(FeatureManagementSectionName, StringComparison.OrdinalIgnoreCase)))
+            if (_configuration.GetChildren().Any(s => s.Key.Equals(ConfigurationFields.FeatureManagementSectionName, StringComparison.OrdinalIgnoreCase)))
             {
                 //
                 // Look for feature definitions under the "FeatureManagement" section
-                return _configuration.GetSection(FeatureManagementSectionName).GetChildren();
+                return _configuration.GetSection(ConfigurationFields.FeatureManagementSectionName).GetChildren();
             }
             else
             {
                 return _configuration.GetChildren();
             }
         }
+
+        private T ParseEnum<T>(string feature, string rawValue, string fieldKeyword)
+            where T: struct, Enum
+        {
+            Debug.Assert(!string.IsNullOrEmpty(rawValue));
+
+            if (!Enum.TryParse(rawValue, ignoreCase: true, out T value))
+            {
+                throw new FeatureManagementException(
+                    FeatureManagementError.InvalidConfigurationSetting,
+                    string.Format(ParseValueErrorString, fieldKeyword, rawValue, feature));
+            }
+
+            return value;
+        }
+
+        private double ParseDouble(string feature, string rawValue, string fieldKeyword)
+        {
+            Debug.Assert(!string.IsNullOrEmpty(rawValue));
+
+            if (!double.TryParse(rawValue, out double value))
+            {
+                throw new FeatureManagementException(
+                    FeatureManagementError.InvalidConfigurationSetting,
+                    string.Format(ParseValueErrorString, fieldKeyword, rawValue, feature));
+            }
+
+            return value;
+        }
     }
 }