Merge pull request #444 from microsoft/main

Merge main into release v3

Author: rossgrambo

README.md

@@ -80,7 +80,7 @@ The feature management library supports appsettings.json as a feature flag sourc
                     "Name": "TimeWindow",
                     "Parameters": {
                         "Start": "Wed, 01 May 2019 13:59:59 GMT",
-                        "End": "Mon, 01 July 2019 00:00:00 GMT"
+                        "End": "Mon, 01 Jul 2019 00:00:00 GMT"
                     }
                 }
             ]
@@ -131,7 +131,7 @@ A `RequirementType` of `All` changes the traversal. First, if there are no filte
             "Name": "TimeWindow",
             "Parameters": {
                 "Start": "Mon, 01 May 2023 13:59:59 GMT",
-                "End": "Sat, 01 July 2023 00:00:00 GMT"
+                "End": "Sat, 01 Jul 2023 00:00:00 GMT"
             }
         },
         {
@@ -163,7 +163,7 @@ The feature management library also supports the usage of the [`Microsoft Featur
                             "name": "Microsoft.TimeWindow",
                             "parameters": {
                                 "Start": "Mon, 01 May 2023 13:59:59 GMT",
-                                "End": "Sat, 01 July 2023 00:00:00 GMT"
+                                "End": "Sat, 01 Jul 2023 00:00:00 GMT"
                             }
                         }
                     ]
@@ -565,13 +565,149 @@ This filter provides the capability to enable a feature based on a time window.
             "Name": "Microsoft.TimeWindow",
             "Parameters": {
                 "Start": "Wed, 01 May 2019 13:59:59 GMT",
-                "End": "Mon, 01 July 2019 00:00:00 GMT"
+                "End": "Mon, 01 Jul 2019 00:00:00 GMT"
             }
         }
     ]
 }
 ```
 
+The time window can be configured to recur periodically. This can be useful for the scenarios where one may need to turn on a feature during a low or high traffic period of a day or certain days of a week. To expand the individual time window to recurring time windows, the recurrence rule should be specified in the `Recurrence` parameter.
+
+**Note:** `Start` and `End` must be both specified to enable `Recurrence`.
+
+``` JavaScript
+"EnhancedPipeline": {
+    "EnabledFor": [
+        {
+            "Name": "Microsoft.TimeWindow",
+            "Parameters": {
+                "Start": "Fri, 22 Mar 2024 20:00:00 GMT",
+                "End": "Sat, 23 Mar 2024 02:00:00 GMT",
+                "Recurrence": {
+                    "Pattern": {
+                        "Type": "Daily",
+                        "Interval": 1
+                    },
+                    "Range": {
+                        "Type": "NoEnd"
+                    }
+                }
+            }
+        }
+    ]
+}
+```
+
+The `Recurrence` settings is made up of two parts: `Pattern` (how often the time window will repeat) and `Range` (for how long the recurrence pattern will repeat). 
+
+#### Recurrence Pattern
+
+There are two possible recurrence pattern types: `Daily` and `Weekly`. For example, a time window could repeat "every day", "every 3 days", "every Monday" or "on Friday per 2 weeks". 
+
+Depending on the type, certain fields of the `Pattern` are required, optional, or ignored.
+
+- `Daily`
+    
+    The daily recurrence pattern causes the time window to repeat based on a number of days between each occurrence.
+
+    | Property | Relevance | Description |
+    |----------|-----------|-------------|
+    | **Type** | Required | Must be set to `Daily`. |
+    | **Interval** | Optional | Specifies the number of days between each occurrence. Default value is 1. |
+
+- `Weekly`
+
+    The weekly recurrence pattern causes the time window to repeat on the same day or days of the week, based on the number of weeks between each set of occurrences.
+
+    | Property | Relevance | Description |
+    |----------|-----------|-------------|
+    | **Type** | Required | Must be set to `Weekly`. |
+    | **DaysOfWeek** | Required | Specifies on which day(s) of the week the event occurs. |
+    | **Interval** | Optional | Specifies the number of weeks between each set of occurrences. Default value is 1. |
+    | **FirstDayOfWeek** | Optional | Specifies which day is considered the first day of the week. Default value is `Sunday`. |
+
+    The following example will repeat the time window every other Monday and Tuesday
+
+    ``` javascript
+    "Pattern": {
+        "Type": "Weekly",
+        "Interval": 2,
+        "DaysOfWeek": ["Monday", "Tuesday"]
+    }
+    ```
+
+**Note:** `Start` must be a valid first occurrence which fits the recurrence pattern. Additionally, the duration of the time window cannot be longer than how frequently it occurs. For example, it is invalid to have a 25-hour time window recur every day.
+
+#### Recurrence Range
+
+There are three possible recurrence range type: `NoEnd`, `EndDate` and `Numbered`.
+
+- `NoEnd`
+
+    The `NoEnd` range causes the recurrence to occur indefinitely.
+
+    | Property | Relevance | Description |
+    |----------|-----------|-------------|
+    | **Type** | Required | Must be set to `NoEnd`. |
+
+- `EndDate`
+
+    The `EndDate` range causes the time window to occur on all days that fit the applicable pattern until the end date.
+
+    | Property | Relevance | Description |
+    |----------|-----------|-------------|
+    | **Type** | Required | Must be set to `EndDate`. |
+    | **EndDate** | Required | 	Specifies the date time to stop applying the pattern. Note that as long as the start time of the last occurrence falls before the end date, the end time of that occurrence is allowed to extend beyond it. |
+
+    The following example will repeat the time window every day until the last occurrence happens on April 1st, 2024.
+
+    ``` javascript
+    "Start": "Fri, 22 Mar 2024 18:00:00 GMT",
+    "End": "Fri, 22 Mar 2024 20:00:00 GMT",
+    "Recurrence":{
+        "Pattern": {
+            "Type": "Daily",
+            "Interval": 1
+        },
+        "Range": {
+            "Type": "EndDate",
+            "EndDate": "Mon, 1 Apr 2024 20:00:00 GMT"
+        }
+    }
+    ```
+
+- `Numbered`
+
+    The `Numbered` range causes the time window to occur a fixed number of times (based on the pattern).
+
+    | Property | Relevance | Description |
+    |----------|-----------|-------------|
+    | **Type** | Required | Must be set to `Numbered`. |
+    | **NumberOfOccurrences** | Required | 	Specifies the number of occurrences. |
+
+    The following example will repeat the time window on Monday and Tuesday until the there are 3 occurrences, which respectively happens on April 1st(Mon), April 2nd(Tue) and April 8th(Mon).
+
+    ``` javascript
+    "Start": "Mon, 1 Apr 2024 18:00:00 GMT",
+    "End": "Mon, 1 Apr 2024 20:00:00 GMT",
+    "Recurrence":{
+        "Pattern": {
+            "Type": "Weekly",
+            "Interval": 1,
+            "DaysOfWeek": ["Monday", "Tuesday"]
+        },
+        "Range": {
+            "Type": "Numbered",
+            "NumberOfOccurrences": 3
+        }
+    }
+    ```
+
+To create a recurrence rule, you must specify both `Pattern` and `Range`. Any pattern type can work with any range type.
+
+**Advanced:** The time zone offset of the `Start` property will apply to the recurrence settings.
+
 ### Microsoft.Targeting
 
 This filter provides the capability to enable a feature for a target audience. An in-depth explanation of targeting is explained in the [targeting](./README.md#Targeting) section below. The filter parameters include an audience object which describes users, groups, excluded users/groups, and a default percentage of the user base that should have access to the feature. Each group object that is listed in the target audience must also specify what percentage of the group's members should have access. If a user is specified in the exclusion section, either directly or if the user is in an excluded group, the feature will be disabled. Otherwise, if a user is specified in the users section directly, or if the user is in the included percentage of any of the group rollouts, or if the user falls into the default rollout percentage then that user will have the feature enabled.
@@ -666,8 +802,8 @@ IFeatureManager fm;
 TargetingContext targetingContext = new TargetingContext
 {
    UserId = userId,
-   Groups = groups;
-}
+   Groups = groups
+};
 
 await fm.IsEnabledAsync(featureName, targetingContext);
 ```

src/Microsoft.FeatureManagement.AspNetCore/FeatureGateAttribute.cs

@@ -90,12 +90,12 @@ public FeatureGateAttribute(RequirementType requirementType, params object[] fea
         public IEnumerable<string> Features { get; }
 
         /// <summary>
-        /// Controls whether any or all features in <see cref="Features"/> should be enabled to pass.
+        /// Controls whether any or all features in <see cref="FeatureGateAttribute.Features"/> should be enabled to pass.
         /// </summary>
         public RequirementType RequirementType { get; }
 
         /// <summary>
-        /// Performs controller action pre-procesing to ensure that at least one of the specified features are enabled.
+        /// Performs controller action pre-procesing to ensure that any or all of the specified features are enabled.
         /// </summary>
         /// <param name="context">The context of the MVC action.</param>
         /// <param name="next">The action delegate.</param>

src/Microsoft.FeatureManagement.AspNetCore/Microsoft.FeatureManagement.AspNetCore.csproj

@@ -4,7 +4,7 @@
   <!-- Official Version -->
   <PropertyGroup>
     <MajorVersion>3</MajorVersion>
-    <MinorVersion>2</MinorVersion>
+    <MinorVersion>3</MinorVersion>
     <PatchVersion>0</PatchVersion>
   </PropertyGroup>
 

src/Microsoft.FeatureManagement/ConfigurationFeatureDefinitionProvider.cs

@@ -133,7 +133,14 @@ public async IAsyncEnumerable<FeatureDefinition> GetAllFeatureDefinitionsAsync()
 
                 //
                 // Underlying IConfigurationSection data is dynamic so latest feature definitions are returned
-                yield return  _definitions.GetOrAdd(featureName, (_) => ReadFeatureDefinition(featureSection));
+                FeatureDefinition definition = _definitions.GetOrAdd(featureName, (_) => ReadFeatureDefinition(featureSection));
+
+                //
+                // Null cache entry possible if someone accesses non-existent flag directly (IsEnabled)
+                if (definition != null)
+                {
+                    yield return definition;
+                }
             }
         }
 

src/Microsoft.FeatureManagement/FeatureFilters/ISystemClock.cs

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+
+using System;
+
+namespace Microsoft.FeatureManagement.FeatureFilters
+{
+    /// <summary>
+    /// Abstracts the system clock to facilitate testing.
+    /// .NET8 offers an abstract class TimeProvider. After we stop supporting .NET version less than .NET8, this ISystemClock should retire.
+    /// </summary>
+    internal interface ISystemClock
+    {
+        /// <summary>
+        /// Retrieves the current system time in UTC.
+        /// </summary>
+        public DateTimeOffset UtcNow { get; }
+    }
+}

src/Microsoft.FeatureManagement/FeatureFilters/PercentageFilter.cs

@@ -4,6 +4,7 @@
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.Logging;
 using Microsoft.FeatureManagement.Utils;
+using System;
 using System.Threading.Tasks;
 
 namespace Microsoft.FeatureManagement.FeatureFilters
@@ -21,9 +22,9 @@ public class PercentageFilter : IFeatureFilter, IFilterParametersBinder
         /// Creates a percentage based feature filter.
         /// </summary>
         /// <param name="loggerFactory">A logger factory for creating loggers.</param>
-        public PercentageFilter(ILoggerFactory loggerFactory)
+        public PercentageFilter(ILoggerFactory loggerFactory = null)
         {
-            _logger = loggerFactory.CreateLogger<PercentageFilter>();
+            _logger = loggerFactory?.CreateLogger<PercentageFilter>();
         }
 
         /// <summary>
@@ -43,6 +44,11 @@ public object BindParameters(IConfiguration filterParameters)
         /// <returns>True if the feature is enabled, false otherwise.</returns>
         public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext context)
         {
+            if (context == null)
+            {
+                throw new ArgumentNullException(nameof(context));
+            }
+
             //
             // Check if prebound settings available, otherwise bind from parameters.
             PercentageFilterSettings settings = (PercentageFilterSettings)context.Settings ?? (PercentageFilterSettings)BindParameters(context.Parameters);
@@ -51,7 +57,7 @@ public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext context)
 
             if (settings.Value < 0)
             {
-                _logger.LogWarning($"The '{Alias}' feature filter does not have a valid '{nameof(settings.Value)}' value for feature '{context.FeatureName}'");
+                _logger?.LogWarning($"The '{Alias}' feature filter does not have a valid '{nameof(settings.Value)}' value for feature '{context.FeatureName}'");
 
                 result = false;
             }

src/Microsoft.FeatureManagement/FeatureFilters/Recurrence/Recurrence.cs

@@ -0,0 +1,21 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+namespace Microsoft.FeatureManagement.FeatureFilters
+{
+    /// <summary>
+    /// A recurrence definition describing how time window recurs
+    /// </summary>
+    public class Recurrence
+    {
+        /// <summary>
+        /// The recurrence pattern specifying how often the time window repeats
+        /// </summary>
+        public RecurrencePattern Pattern { get; set; }
+
+        /// <summary>
+        /// The recurrence range specifying how long the recurrence pattern repeats
+        /// </summary>
+        public RecurrenceRange Range { get; set; }
+    }
+}