App Configuration: recurring time window filter

sdk/spring/spring-cloud-azure-feature-management/README.md

@@ -41,10 +41,10 @@ feature-management:
     feature-v:
       enabled-for:
         -
-          name: TimeWindowFilter
+          name: Microsoft.TimeWindow
           parameters:
-            time-window-filter-setting-start: "Wed, 01 May 2019 13:59:59 GMT"
-            time-window-filter-setting-end: "Mon, 01 July 2019 00:00:00 GMT"
+            start: "Wed, 01 May 2019 13:59:59 GMT"
+            end: "Mon, 01 July 2019 00:00:00 GMT"
     feature-w:
       evaluate: false
       enabled-for:
@@ -182,20 +182,183 @@ feature-management:
 
 ### TimeWindowFilter
 
-This filter provides the capability to enable a feature based on a time window. If only `time-window-filter-setting-end` is specified, the feature will be considered on until that time. If only start is specified, the feature will be considered on at all points after that time. If both are specified the feature will be considered valid between the two times.
+This filter provides the capability to enable a feature based on a time window. If only `end` is specified, the feature will be considered enabled until that time. If only `start` is specified, the feature will be considered enabled at all points after that time. If both are specified the feature will be considered enabled between the two times.
 
 ```yaml
 feature-management:
   feature-flags:
     feature-v:
       enabled-for:
         -
-         name: TimeWindowFilter
+          name: Microsoft.TimeWindow
           parameters:
-            time-window-filter-setting-start: "Wed, 01 May 2019 13:59:59 GMT",
-            time-window-filter-setting-end: "Mon, 01 July 2019 00:00:00 GMT"
+            start: "Wed, 01 May 2019 13:59:59 GMT"
+            end: "Mon, 01 July 2019 00:00:00 GMT"
 ```
 
+The time window can be configured to recur periodically. This can be useful in the scenario where you have to enable/disable a feature during low or high traffic periods of a day or for certain days of the week. To expand the individual time window to recurring time windows, the recurrence rule should be specified in the `recurrence` parameter.
+
+
+```yaml
+feature-management:
+  feature-flags:
+    feature-v:
+      enabled-for:
+        -
+          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: "Numbered"
+                numberOfOccurrences: 3
+```
+To create a recurrence rule, you need to specify 3 parts: `start`, `end` and `recurrence`. 
+The `start` and `end` parameters define the time window which need to recur periodically. 
+The `recurrence` parameter is made up of two parts: `pattern` (how often the time window will repeat) and `range` (for how long the recurrence pattern will repeat). To create a recurrence rule, you must specify both `pattern` and `range`. Any pattern type can work with any range type. 
+The time zone offset of the `start` property will apply to the recurrence settings.
+
+**Note:** `start` must be a valid first occurrence which fits the recurrence pattern. For example, if we define to repeat on every other Monday and Tuesday, then the start time should be in Monday or Tuesday. <br /> 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 Pattern
+
+There are two possible recurrence pattern types: `Daily` and `Weekly`. 
+
+`Daily` causes an event to repeat based on a number of days between each occurrence. For example, "every day" or "every 3 days".
+
+`Weekly` causes an event to repeat on the same day or days of the week, based on the number of weeks between each set of occurrences. For example, "every Monday" or "every other Friday".
+
+* Parameters
+
+  Property | Relevance | Description
+  -----------|-------|-----
+  **type** | Required  | `Daily`/`Weekly`.
+  **interval** | Optional  | Specifies the interval between each start time of occurrence. Default value is 1. <br/>For example, if the interval is 2 with `Daily` type, and current occurrence is 2:00 AM ~ 3:00 AM on 2024/05/11, then the next occurrence should be 2:00 AM ~ 3:00 AM on 2024/05/13
+  **daysOfWeek** | Required/Optional  | Specifies on which day(s) of the week the event occurs. It's required when `Weekly` type, negatively for `Daily` type. 
+  **firstDayOfWeek** | Optional  | Specifies which day is considered the first day of the week. Default value is `Sunday`. Negatively for `Daily` type. 
+
+  * Example
+    * Daily
+
+        The following example will repeat from 2:00 AM to 3:00 AM on every 2 days
+
+        ```yaml
+        start: "Mon, 13 May 2024 02:00:00 GMT"
+        end: "Mon, 13 May 2024 03:00:00 GMT"
+        recurrence:
+          pattern:
+            type: "Daily"
+            interval: 2
+          range:
+            type: "NoEnd"
+        ```
+
+    * Weekly
+
+      The following example will repeat from 2:00 AM to 3:00 AM on every other Monday and Tuesday
+
+        ```yaml
+        start: "Mon, 13 May 2024 02:00:00 GMT"
+        end: "Mon, 13 May 2024 03:00:00 GMT"
+        recurrence:
+          pattern:
+            type: "Weekly"
+            interval: 2
+            daysOfWeek: 
+              - Monday
+              - Tuesday
+          range:
+            type: "NoEnd"
+        ```
+      The following example shows a time window starts on one day and ends on another, repeat every week.
+
+        ```yaml
+        start: "Mon, 13 May 2024 02:00:00 GMT"
+        end: "Mon, 14 May 2024 03:00:00 GMT"
+        recurrence:
+          pattern:
+            type: "Weekly"
+            interval: 1
+            daysOfWeek: 
+              - Monday
+          range:
+            type: "NoEnd"
+        ```
+
+
+#### Recurrence Range
+
+There are three possible recurrence range type: `NoEnd`, `EndDate` and `Numbered`.
+
+* Parameter
+
+    Property | Relevance | Description                                                                           |
+    -----------|---------------|-------------
+    **type** | Required  | `NoEnd`/`EndDate`/`Numbered`.
+    **endDate** | Required/Optional  |  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. <br /> It's required for `EndDate` type, negatively for `NoEnd` and `Numbered` type.
+    **NumberOfOccurrences** | Required/Optional | Specifies the number of days that it will occur. <br /> It's required for `Numbered` type, negatively for `NoEnd` and `EndDate` type.
+
+  * Example
+    * `NoEnd`
+
+      The `NoEnd` range causes the recurrence to occur indefinitely.
+
+      The following example will repeat from 6:00 PM to 8:00 PM every day.
+
+      ``` yaml
+        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: "NoEnd"
+      ```
+
+    * `EndDate`
+
+      The `EndDate` range causes the time window to occur on all days that fit the applicable pattern until the end date.
+
+      The following example will repeat from 6:00 PM to 8:00 PM every day until the last occurrence happens on April 1st, 2024.
+
+      ``` yaml
+      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 days (based on the pattern).
+
+      The following example will repeat from 6:00 PM to 8:00 PM on Monday and Tuesday until the there are 3 occurrences, which respectively happens on 2024/04/01(Mon), 2024/04/02(Tue) and 2024/04/08(Mon).
+
+        ``` yaml
+        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
+        ```
+
 ### TargetingFilter
 
 This filter provides the capability to enable a feature for a target audience. An in-depth explanation of targeting is explained in the targeting section below. The filter parameters include an audience object which describes users, groups, and a default percentage of the user base that should have access to the feature, and an exclusion object for users and groups that should never be targeted. 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 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.

sdk/spring/spring-cloud-azure-feature-management/src/main/java/com/azure/spring/cloud/feature/management/filters/TargetingFilter.java

@@ -7,13 +7,12 @@
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
 import java.util.ArrayList;
-import java.util.Collection;
 import java.util.HashMap;
 import java.util.List;
-import java.util.Locale;
 import java.util.Map;
 import java.util.Optional;
 
+import com.azure.spring.cloud.feature.management.implementation.FeatureFilterUtils;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.util.StringUtils;
@@ -84,7 +83,7 @@ public class TargetingFilter implements FeatureFilter {
 
     /**
      * Filter for targeting a user/group/percentage of users.
-     * 
+     *
      * @param contextAccessor Accessor for identifying the current user/group when evaluating
      */
     public TargetingFilter(TargetingContextAccessor contextAccessor) {
@@ -94,7 +93,7 @@ public TargetingFilter(TargetingContextAccessor contextAccessor) {
 
     /**
      * `Microsoft.TargetingFilter` evaluates a user/group/overall rollout of a feature.
-     * 
+     *
      * @param contextAccessor Context for evaluating the users/groups.
      * @param options enables customization of the filter.
      */
@@ -126,13 +125,13 @@ public boolean evaluate(FeatureFilterEvaluationContext context) {
             parameters = (Map<String, Object>) audienceObject;
         }
 
-        updateValueFromMapToList(parameters, USERS);
-        updateValueFromMapToList(parameters, GROUPS);
+        FeatureFilterUtils.updateValueFromMapToList(parameters, USERS);
+        FeatureFilterUtils.updateValueFromMapToList(parameters, GROUPS);
 
         Audience audience;
-        String exclusionValue = getKeyCase(parameters, EXCLUSION_CAMEL);
-        String exclusionUserValue = getKeyCase((Map<String, Object>) parameters.get(exclusionValue), "Users");
-        String exclusionGroupsValue = getKeyCase((Map<String, Object>) parameters.get(exclusionValue), "Groups");
+        String exclusionValue = FeatureFilterUtils.getKeyCase(parameters, EXCLUSION_CAMEL);
+        String exclusionUserValue = FeatureFilterUtils.getKeyCase((Map<String, Object>) parameters.get(exclusionValue), "Users");
+        String exclusionGroupsValue = FeatureFilterUtils.getKeyCase((Map<String, Object>) parameters.get(exclusionValue), "Groups");
 
         if (((Map<String, Object>) parameters.getOrDefault(exclusionValue, new HashMap<>()))
             .get(exclusionUserValue) instanceof List) {
@@ -194,13 +193,6 @@ public boolean evaluate(FeatureFilterEvaluationContext context) {
         return isTargeted(defaultContextId, audience.getDefaultRolloutPercentage());
     }
 
-    private String getKeyCase(Map<String, Object> parameters, String key) {
-        if (parameters != null && parameters.containsKey(key)) {
-            return key;
-        }
-        return key.toLowerCase(Locale.getDefault());
-    }
-
     private boolean targetUser(String userId, List<String> users) {
         return userId != null && users != null && users.stream().anyMatch(user -> equals(userId, user));
     }
@@ -234,7 +226,7 @@ private boolean validateTargetingContext(TargetingFilterContext targetingContext
 
     /**
      * Computes the percentage that the contextId falls into.
-     * 
+     *
      * @param contextId Id of the context being targeted
      * @return the bucket value of the context id
      * @throws TargetingException Unable to create hash of target context
@@ -265,8 +257,8 @@ private boolean isTargeted(String contextId, double percentage) {
 
     /**
      * Validates the settings of a targeting filter.
-     * 
-     * @param settings targeting filter settings
+     *
+     * @param audience targeting filter settings
      * @throws TargetingException when a required parameter is missing or percentage value is greater than 100.
      */
     void validateSettings(Audience audience) {
@@ -303,7 +295,7 @@ void validateSettings(Audience audience) {
 
     /**
      * Checks if two strings are equal, ignores case if configured to.
-     * 
+     *
      * @param s1 string to compare
      * @param s2 string to compare
      * @return true if the strings are equal
@@ -314,21 +306,4 @@ private boolean equals(String s1, String s2) {
         }
         return s1.equals(s2);
     }
-
-    /**
-     * Looks at the given key in the parameters and coverts it to a list if it is currently a map. Used for updating
-     * fields in the targeting filter.
-     * 
-     * @param <T> Type of object inside of parameters for the given key
-     * @param parameters map of generic objects
-     * @param key key of object int the parameters map
-     */
-    @SuppressWarnings("unchecked")
-    private void updateValueFromMapToList(Map<String, Object> parameters, String key) {
-        Object objectMap = parameters.get(key);
-        if (objectMap instanceof Map) {
-            Collection<Object> toType = ((Map<String, Object>) objectMap).values();
-            parameters.put(key, toType);
-        }
-    }
 }