Support recurring time window filter for TimeWindowFilter

README.md

@@ -489,6 +489,52 @@ This filter provides the capability to enable a feature based on a time window.
 }
 ```
 
+This filter also provides the capability to enable a feature during some recurring time windows. The recurring time windows act as the additional filters of evaluation, supplementing the time window defined by the `Start` and `End`. If any recurring time window filter is specified, the feature will only be enabled when the current time falls between the `Start` and `End`, and also falls within a recurring time window listed in the `Filters`.
+We can see some Crontab expressions are listed under the `Filters`, which specify the recurring time windows. 
+``` JavaScript
+"EnhancedPipeline": {
+    "EnabledFor": [
+        {
+            "Name": "Microsoft.TimeWindow",
+            "Parameters": {
+                "Start": "2023-09-06T00:00:00+08:00",
+                "Filters": [
+                    // 18:00-20:00 on weekdays
+                    "* 18-19 * * Mon-Fri",
+                    // 18:00-22:00 on weekends
+                    "* 18-21 * * Sat,Sun"
+                ]
+            }
+        }
+    ]
+}
+```
+In UNIX, the usage of Crontab expression is to represent the time to execute a command. The Crontab serves as a schedule. The Crontab expression is designed to represent discrete time point rather than continuous time span. For example, the Cron job “* * * * * echo hi >> log” will execute “echo hi >> log” at the beginning of each minute. 
+
+However, when the time granularity is at minute-level, we can consider it as a continuous time intervals. For example, the Crontab expression “* 16 * * *” means “at every minute past the 16th hour of the day”. We can intuitively consider it as the time span 16:00-17:00. As a result, the recurring time window can be represented by a Crontab expression. 
+
+The Crontab format can be refered to the [linux man page](https://man7.org/linux/man-pages/man5/crontab.5.html). We allow the usage of ranges, lists and step values. Randomization is not supported.
+
+The crontab format has five time fields separated by at least one blank:
+
+```
+{minute} {hour} {day-of-month} {month} {day-of-week}
+```
+
+| Crontab Expression Example | Recurring Time Window |
+|--------|--------|
+|* 16 * * 1-5 | 16:00-17:00 every weekday |
+| * 6-9,16-19 * * * | 6:00-10:00 and 16:00-20:00 every day |
+| * * 1,15 * 1 | the first and fifteenth day of each month, as well as on every Monday|
+| * * * 8 5 | every Friday in August |
+| * 18-21 25 12 * | 18:00-22:00 on Dec 25th |
+
+The Crontab does not contain the information of UTC time offset.
+- If the UTC offset is specified in `Start`, it will also be applied to Crontabs listed in `Filters`. 
+- If the UTC offset of `Start` is not specified and the UTC offset of `End` is specified, the UTC offset of `End` will be applied to Crontabs listed in `Filters`. 
+- Otherwise, we will use the default UTC offset: UTC+0:00. 
+
+In the above example, the `Start` is "2023-09-06T00:00:00+08:00", as a result, the UTC+8:00 will be also applied to the recurring time window filters: 18:00-20:00 on weekdays and 18:00-22:00 on weekends.
 #### 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.

src/Microsoft.FeatureManagement/FeatureFilters/Cron/CronExpression.cs

@@ -0,0 +1,121 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+//
+using System;
+
+namespace Microsoft.FeatureManagement.FeatureFilters.Cron
+{
+    /// <summary>
+    /// The Cron expression with Minute, Hour, Day of month, Month, Day of week fields.
+    /// </summary>
+    internal class CronExpression
+    {
+        private static readonly int NumberOfFields = 5;
+
+        private readonly CronField _minute;
+        private readonly CronField _hour;
+        private readonly CronField _dayOfMonth;
+        private readonly CronField _month;
+        private readonly CronField _dayOfWeek;
+
+        private CronExpression(CronField minute, CronField hour, CronField dayOfMonth, CronField month, CronField dayOfWeek)
+        {
+            _minute = minute;
+            _hour = hour;
+            _dayOfMonth = dayOfMonth;
+            _month = month;
+            _dayOfWeek = dayOfWeek;
+        }
+
+        /// <summary>
+        /// Check whether the given expression can be parsed by a CronExpression.
+        /// If the expression is invalid, an ArgumentException will be thrown.
+        /// </summary>
+        /// <param name="expression">The expression to parse.</param>
+        /// <returns>A parsed CronExpression.</returns>
+        public static CronExpression Parse(string expression)
+        {
+            if (expression == null)
+            {
+                throw new ArgumentNullException(nameof(expression));
+            }
+
+            string InvalidCronExpressionErrorMessage = $"The provided Cron expression: '{expression}' is invalid.";
+
+            var fields = new string[NumberOfFields];
+
+            int i = 0, pos = 0;
+
+            while (i < expression.Length)
+            {
+                if (char.IsWhiteSpace(expression[i]))
+                {
+                    i++;
+
+                    continue;
+                }
+
+                if (pos >= fields.Length)
+                {
+                    throw new ArgumentException(InvalidCronExpressionErrorMessage, nameof(expression));
+                }
+
+                int start = i; // Start of a field
+
+                while (i < expression.Length && !char.IsWhiteSpace(expression[i]))
+                {
+                    i++;
+                }
+
+                fields[pos] = expression.Substring(start, i - start);
+
+                pos++;
+            }
+
+            if (CronField.TryParse(CronFieldKind.Minute, fields[0], out CronField minute) &&
+                CronField.TryParse(CronFieldKind.Hour, fields[1], out CronField hour) &&
+                CronField.TryParse(CronFieldKind.DayOfMonth, fields[2], out CronField dayOfMonth) &&
+                CronField.TryParse(CronFieldKind.Month, fields[3], out CronField month) &&
+                CronField.TryParse(CronFieldKind.DayOfWeek, fields[4], out CronField dayOfWeek))
+            {
+                return new CronExpression(minute, hour, dayOfMonth, month, dayOfWeek);
+            }
+            else
+            {
+                throw new ArgumentException(InvalidCronExpressionErrorMessage, nameof(expression));
+            }
+        }
+
+        /// <summary>
+        /// Checks whether the Cron expression is satisfied by the given timestamp.
+        /// </summary>
+        /// <param name="time">The timestamp to check.</param>
+        /// <returns>True if the Cron expression is satisfied by the give timestamp, otherwise false.</returns>
+        public bool IsSatisfiedBy(DateTimeOffset time)
+        {
+            /*
+            The current time is said to be satisfied by the Cron expression when the 'minute', 'hour', and 'month of the year' fields match the current time, 
+            and at least one of the two 'day' fields ('day of month', or 'day of week') match the current time.
+            If both 'day' fields are restricted (i.e., do not contain the "*" character), the current time will be considered as satisfied when it match either 'day' field and other fields.
+            If exactly one of 'day' fields are restricted, the current time will be considered as satisfied when it match both 'day' fields and other fields.
+             */
+            bool isDayMatched;
+
+            if (!_dayOfMonth.MatchesAll && !_dayOfWeek.MatchesAll)
+            {
+                isDayMatched = (_dayOfMonth.Match((int)time.Day) || _dayOfWeek.Match((int)time.DayOfWeek)) &&
+                               _month.Match((int)time.Month);
+            }
+            else
+            {
+                isDayMatched = _dayOfMonth.Match((int)time.Day) &&
+                               _dayOfWeek.Match((int)time.DayOfWeek) &&
+                               _month.Match((int)time.Month);
+            }
+
+            return isDayMatched &&
+                   _hour.Match((int)time.Hour) &&
+                   _minute.Match((int)time.Minute);
+        }
+    }
+}