App Configuration: recurring time window filter

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

@@ -182,7 +182,7 @@ 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 on until that time. If only `Start` is specified, the feature will be considered on at all points after that time.
 
 ```yaml
 feature-management:
@@ -192,10 +192,136 @@ feature-management:
         -
          name: TimeWindowFilter
           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 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`.
+
+```yaml
+feature-management:
+  feature-flags:
+    feature-v:
+      enabled-for:
+        -
+         name: TimeWindowFilter
+          parameters:
+            start: "Fri, 22 Mar 2024 20:00:00 GMT",
+            end: "Mon, 01 July 2019 00: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
+
+    ```yaml
+    pattern:
+        type: "Weekly",
+        interval: 1,
+        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.
+
+    ``` 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 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).
+
+    ``` 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
+    ```
+
+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.
+
 ### 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/FeatureManagementConfiguration.java

@@ -3,6 +3,9 @@
 package com.azure.spring.cloud.feature.management;
 
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.cache.CacheManager;
+import org.springframework.cache.annotation.EnableCaching;
+import org.springframework.cache.concurrent.ConcurrentMapCacheManager;
 import org.springframework.context.ApplicationContext;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
@@ -15,6 +18,7 @@
  */
 @Configuration
 @EnableConfigurationProperties({ FeatureManagementConfigProperties.class, FeatureManagementProperties.class })
+@EnableCaching
 class FeatureManagementConfiguration {
 
     /**
@@ -30,4 +34,9 @@ FeatureManager featureManager(ApplicationContext context,
         FeatureManagementProperties featureManagementConfigurations, FeatureManagementConfigProperties properties) {
         return new FeatureManager(context, featureManagementConfigurations, properties);
     }
+
+    @Bean
+    public CacheManager cacheManager() {
+        return new ConcurrentMapCacheManager("settings");
+    }
 }

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

@@ -2,16 +2,23 @@
 // Licensed under the MIT License.
 package com.azure.spring.cloud.feature.management.filters;
 
+import com.azure.spring.cloud.feature.management.implementation.timewindow.TimeWindowFilterSettings;
+import com.azure.spring.cloud.feature.management.implementation.timewindow.recurrence.RecurrenceCachedService;
+import com.azure.spring.cloud.feature.management.implementation.timewindow.recurrence.RecurrenceConstants;
 import com.azure.spring.cloud.feature.management.models.FeatureFilterEvaluationContext;
+import com.fasterxml.jackson.databind.MapperFeature;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.json.JsonMapper;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
-import org.springframework.util.StringUtils;
 
+import java.time.Duration;
 import java.time.ZonedDateTime;
-import java.time.format.DateTimeFormatter;
-import java.time.format.DateTimeParseException;
+import java.util.Collection;
+import java.util.Map;
 
 import static com.azure.spring.cloud.feature.management.models.FilterParameters.TIME_WINDOW_FILTER_SETTING_END;
+import static com.azure.spring.cloud.feature.management.models.FilterParameters.TIME_WINDOW_FILTER_SETTING_RECURRENCE;
 import static com.azure.spring.cloud.feature.management.models.FilterParameters.TIME_WINDOW_FILTER_SETTING_START;
 
 /**
@@ -26,6 +33,8 @@ public TimeWindowFilter() {
     }
 
     private static final Logger LOGGER = LoggerFactory.getLogger(TimeWindowFilter.class);
+    private static final ObjectMapper OBJECT_MAPPER = JsonMapper.builder()
+        .configure(MapperFeature.ACCEPT_CASE_INSENSITIVE_PROPERTIES, true).build();
 
     /**
      * Evaluates whether a feature is enabled based on a configurable time window.
@@ -35,38 +44,55 @@ public TimeWindowFilter() {
      */
     @Override
     public boolean evaluate(FeatureFilterEvaluationContext context) {
-        String start = (String) context.getParameters().get(TIME_WINDOW_FILTER_SETTING_START);
-        String end = (String) context.getParameters().get(TIME_WINDOW_FILTER_SETTING_END);
+        final Map<String, Object> parameters = context.getParameters();
+        final Object recurrenceObject = parameters.get(TIME_WINDOW_FILTER_SETTING_RECURRENCE);
+        if (recurrenceObject != null) {
+            final Map<String, Object> recurrenceParameters = (Map<String, Object>) recurrenceObject;
+            final Object patternObj = recurrenceParameters.get(RecurrenceConstants.RECURRENCE_PATTERN);
+            if (patternObj != null) {
+                updateValueFromMapToList((Map<String, Object>) patternObj, RecurrenceConstants.RECURRENCE_PATTERN_DAYS_OF_WEEK);
+            }
+        }
 
-        ZonedDateTime now = ZonedDateTime.now();
+        final TimeWindowFilterSettings settings = OBJECT_MAPPER.convertValue(context.getParameters(), TimeWindowFilterSettings.class);
+        final ZonedDateTime now = ZonedDateTime.now();
 
-        if (!StringUtils.hasText(start) && !StringUtils.hasText(end)) {
+        if (settings.getStart() == null && settings.getEnd() == null) {
             LOGGER.warn("The {} feature filter is not valid for feature {}. It must specify either {}, {}, or both.",
                 this.getClass().getSimpleName(), context.getName(), TIME_WINDOW_FILTER_SETTING_START,
                 TIME_WINDOW_FILTER_SETTING_END);
             return false;
         }
-
-        ZonedDateTime startTime = null;
-        ZonedDateTime endTime = null;
-
-        try {
-            startTime = StringUtils.hasText(start)
-                ? ZonedDateTime.parse(start, DateTimeFormatter.ISO_DATE_TIME)
-                : null;
-            endTime = StringUtils.hasText(end)
-                ? ZonedDateTime.parse(end, DateTimeFormatter.ISO_DATE_TIME)
-                : null;
-        } catch (DateTimeParseException e) {
-            startTime = StringUtils.hasText(start)
-                ? ZonedDateTime.parse(start, DateTimeFormatter.RFC_1123_DATE_TIME)
-                : null;
-            endTime = StringUtils.hasText(end)
-                ? ZonedDateTime.parse(end, DateTimeFormatter.RFC_1123_DATE_TIME)
-                : null;
+
+        if ((settings.getStart() == null || now.isAfter(settings.getStart()))
+            && (settings.getEnd() == null || now.isBefore(settings.getEnd()))) {
+            return true;
+        }
+
+        if (settings.getRecurrence() != null) {
+            final Duration timeWindowSpan = Duration.between(settings.getStart(), settings.getEnd());
+            ZonedDateTime closestRecurrence = RecurrenceCachedService.getClosestTime(settings, now);
+
+            // Recalculate the closest recurrence if we have passed the cached time window.
+            if (now.isAfter(closestRecurrence.plus(timeWindowSpan))) {
+                closestRecurrence = RecurrenceCachedService.updateClosestTime(settings, now);
+            }
+
+            if (closestRecurrence == null || now.isBefore(closestRecurrence)) {
+                return false;
+            }
+
+            return now.isBefore(closestRecurrence.plus(timeWindowSpan));
         }
-        return (!StringUtils.hasText(start) || now.isAfter(startTime))
-            && (!StringUtils.hasText(end) || now.isBefore(endTime));
+
+        return false;
     }
 
+    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);
+        }
+    }
 }

sdk/spring/spring-cloud-azure-feature-management/src/main/java/com/azure/spring/cloud/feature/management/implementation/timewindow/TimeWindowFilterSettings.java

@@ -0,0 +1,76 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.azure.spring.cloud.feature.management.implementation.timewindow;
+
+import com.azure.spring.cloud.feature.management.implementation.timewindow.recurrence.Recurrence;
+
+import java.time.ZonedDateTime;
+
+public class TimeWindowFilterSettings {
+    /**
+     * An optional start time used to determine when a feature should be enabled.
+     * If no start time is specified the time window is considered to have already started.
+     * */
+    private ZonedDateTime start;
+    /**
+     * An optional end time used to determine when a feature should be disabled.
+     * If no end time is specified the time window is considered to never end.
+     * */
+    private ZonedDateTime end;
+    /**
+     * Add-on recurrence rule allows the time window defined by Start and End to recur.
+     * The rule specifies both how often the time window repeats and for how long.
+     * */
+    private Recurrence recurrence;
+
+    /**
+     * @param startTime the start time to determine when a feature should be enabled
+     * */
+    public void setStart(String startTime) {
+        this.start = TimeWindowUtils.convertStringToDate(startTime);
+    }
+
+    /**
+     * @return start time
+     * */
+    public ZonedDateTime getStart() {
+        return start;
+    }
+
+    /**
+     * @param endTime the end time to determine when a feature should be disabled
+     * */
+    public void setEnd(String endTime) {
+        this.end = TimeWindowUtils.convertStringToDate(endTime);
+    }
+
+    /**
+     * @return end time
+     * */
+    public ZonedDateTime getEnd() {
+        return end;
+    }
+
+    /**
+     * @param recurrence the recurrence rule to specify both how often the time window repeats and for how long
+     * */
+    public void setRecurrence(Recurrence recurrence) {
+        this.recurrence = recurrence;
+    }
+
+    /**
+     * @return the recurrence rule
+     * */
+    public Recurrence getRecurrence() {
+        return recurrence;
+    }
+
+    @Override
+    public String toString() {
+        return "TimeWindowFilterSettings{"
+            + "start=" + start
+            + ", end=" + end
+            + ", recurrence=" + recurrence
+            + '}';
+    }
+}