Support recurrence for TimeWindowFilter (#266)

* improvement & target on main branch * remove duplicated null check * remove redundant if * improvement * resolve comments * fix typo * update * use enum * Update testcases * fix bug * update * update the logic of FindWeeklyPreviousOccurrence * fix bug * add comments * update * fix bug & add testcases * update * update comment * test * update comments * update * update * add testcase * remove monthly/yearly recurrence pattern * do not mention monthly and yearly pattern * add more comments * update the algorithm to find weekly previous occurrence * update * fix typo * update * rename variable * cache added & do validation for only once * add comments * add more testcases * add more test * not include the end of a time window * move recurrence validation to RecurrenceValidator * README updated * update readme * update CalculateSurroundingOccurrences method * add CalculateClosestStart method * testcase updated * update * use ISystemClock for testing & add limit on time window duration * add testcase for timezone * update * update comments * change method type * remove unused reference * rename variable * remove used reference * remove empty lines
microsoft · Apr 23, 2024 · 44033d2 · 44033d2
1 parent a63856c
commit 44033d2
Show file tree

Hide file tree

Showing 18 changed files with 3,046 additions and 33 deletions.
diff --git a/README.md b/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.

diff --git a/src/Microsoft.FeatureManagement/FeatureFilters/ISystemClock.cs b/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; }
+    }
+}
diff --git a/src/Microsoft.FeatureManagement/FeatureFilters/Recurrence/Recurrence.cs b/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; }
+    }
+}