Feature request: Time based feature flags actions

CHANGELOG.md

@@ -4,6 +4,18 @@
 <a name="unreleased"></a>
 # Unreleased
 
+## Maintenance
+
+* **deps:** bump future from 0.18.2 to 0.18.3 ([#1836](https://github.com/awslabs/aws-lambda-powertools-python/issues/1836))
+* **deps-dev:** bump mkdocs-material from 9.0.3 to 9.0.4 ([#1833](https://github.com/awslabs/aws-lambda-powertools-python/issues/1833))
+* **deps-dev:** bump mypy-boto3-logs from 1.26.43 to 1.26.49 ([#1834](https://github.com/awslabs/aws-lambda-powertools-python/issues/1834))
+* **deps-dev:** bump mypy-boto3-secretsmanager from 1.26.40 to 1.26.49 ([#1835](https://github.com/awslabs/aws-lambda-powertools-python/issues/1835))
+* **deps-dev:** bump mypy-boto3-lambda from 1.26.18 to 1.26.49 ([#1832](https://github.com/awslabs/aws-lambda-powertools-python/issues/1832))
+* **deps-dev:** bump aws-cdk-lib from 2.59.0 to 2.60.0 ([#1831](https://github.com/awslabs/aws-lambda-powertools-python/issues/1831))
+
+
+<a name="v2.6.0"></a>
+## [v2.6.0] - 2023-01-12
 ## Bug Fixes
 
 * **api_gateway:** fixed custom metrics issue when using debug mode ([#1827](https://github.com/awslabs/aws-lambda-powertools-python/issues/1827))
@@ -15,29 +27,30 @@
 
 ## Maintenance
 
+* update v2 layer ARN on documentation
 * **deps:** bump pydantic from 1.10.2 to 1.10.4 ([#1817](https://github.com/awslabs/aws-lambda-powertools-python/issues/1817))
 * **deps:** bump zgosalvez/github-actions-ensure-sha-pinned-actions from 2.0.1 to 2.0.3 ([#1801](https://github.com/awslabs/aws-lambda-powertools-python/issues/1801))
 * **deps:** bump release-drafter/release-drafter from 5.21.1 to 5.22.0 ([#1802](https://github.com/awslabs/aws-lambda-powertools-python/issues/1802))
-* **deps:** bump zgosalvez/github-actions-ensure-sha-pinned-actions from 2.0.3 to 2.0.4 ([#1821](https://github.com/awslabs/aws-lambda-powertools-python/issues/1821))
 * **deps:** bump gitpython from 3.1.29 to 3.1.30 ([#1812](https://github.com/awslabs/aws-lambda-powertools-python/issues/1812))
+* **deps:** bump zgosalvez/github-actions-ensure-sha-pinned-actions from 2.0.3 to 2.0.4 ([#1821](https://github.com/awslabs/aws-lambda-powertools-python/issues/1821))
 * **deps:** bump peaceiris/actions-gh-pages from 3.9.0 to 3.9.1 ([#1814](https://github.com/awslabs/aws-lambda-powertools-python/issues/1814))
-* **deps-dev:** bump coverage from 7.0.4 to 7.0.5 ([#1829](https://github.com/awslabs/aws-lambda-powertools-python/issues/1829))
+* **deps-dev:** bump mkdocs-material from 8.5.11 to 9.0.2 ([#1808](https://github.com/awslabs/aws-lambda-powertools-python/issues/1808))
 * **deps-dev:** bump mypy-boto3-ssm from 1.26.11.post1 to 1.26.43 ([#1819](https://github.com/awslabs/aws-lambda-powertools-python/issues/1819))
 * **deps-dev:** bump mypy-boto3-logs from 1.26.27 to 1.26.43 ([#1820](https://github.com/awslabs/aws-lambda-powertools-python/issues/1820))
 * **deps-dev:** bump filelock from 3.8.2 to 3.9.0 ([#1816](https://github.com/awslabs/aws-lambda-powertools-python/issues/1816))
 * **deps-dev:** bump mypy-boto3-cloudformation from 1.26.11.post1 to 1.26.35.post1 ([#1818](https://github.com/awslabs/aws-lambda-powertools-python/issues/1818))
-* **deps-dev:** bump mkdocs-material from 8.5.11 to 9.0.2 ([#1808](https://github.com/awslabs/aws-lambda-powertools-python/issues/1808))
+* **deps-dev:** bump ijson from 3.1.4 to 3.2.0.post0 ([#1815](https://github.com/awslabs/aws-lambda-powertools-python/issues/1815))
 * **deps-dev:** bump coverage from 6.5.0 to 7.0.3 ([#1806](https://github.com/awslabs/aws-lambda-powertools-python/issues/1806))
 * **deps-dev:** bump flake8-builtins from 2.0.1 to 2.1.0 ([#1799](https://github.com/awslabs/aws-lambda-powertools-python/issues/1799))
-* **deps-dev:** bump ijson from 3.1.4 to 3.2.0.post0 ([#1815](https://github.com/awslabs/aws-lambda-powertools-python/issues/1815))
+* **deps-dev:** bump coverage from 7.0.3 to 7.0.4 ([#1822](https://github.com/awslabs/aws-lambda-powertools-python/issues/1822))
 * **deps-dev:** bump mypy-boto3-secretsmanager from 1.26.12 to 1.26.40 ([#1811](https://github.com/awslabs/aws-lambda-powertools-python/issues/1811))
 * **deps-dev:** bump isort from 5.11.3 to 5.11.4 ([#1809](https://github.com/awslabs/aws-lambda-powertools-python/issues/1809))
 * **deps-dev:** bump aws-cdk-lib from 2.55.1 to 2.59.0 ([#1810](https://github.com/awslabs/aws-lambda-powertools-python/issues/1810))
 * **deps-dev:** bump importlib-metadata from 5.1.0 to 6.0.0 ([#1804](https://github.com/awslabs/aws-lambda-powertools-python/issues/1804))
-* **deps-dev:** bump coverage from 7.0.3 to 7.0.4 ([#1822](https://github.com/awslabs/aws-lambda-powertools-python/issues/1822))
+* **deps-dev:** bump mkdocs-material from 9.0.2 to 9.0.3 ([#1823](https://github.com/awslabs/aws-lambda-powertools-python/issues/1823))
 * **deps-dev:** bump black from 22.10.0 to 22.12.0 ([#1770](https://github.com/awslabs/aws-lambda-powertools-python/issues/1770))
 * **deps-dev:** bump flake8-black from 0.3.5 to 0.3.6 ([#1792](https://github.com/awslabs/aws-lambda-powertools-python/issues/1792))
-* **deps-dev:** bump mkdocs-material from 9.0.2 to 9.0.3 ([#1823](https://github.com/awslabs/aws-lambda-powertools-python/issues/1823))
+* **deps-dev:** bump coverage from 7.0.4 to 7.0.5 ([#1829](https://github.com/awslabs/aws-lambda-powertools-python/issues/1829))
 * **deps-dev:** bump types-requests from 2.28.11.5 to 2.28.11.7 ([#1795](https://github.com/awslabs/aws-lambda-powertools-python/issues/1795))
 
 
@@ -2748,7 +2761,8 @@
 * Merge pull request [#5](https://github.com/awslabs/aws-lambda-powertools-python/issues/5) from jfuss/feat/python38
 
 
-[Unreleased]: https://github.com/awslabs/aws-lambda-powertools-python/compare/v2.5.0...HEAD
+[Unreleased]: https://github.com/awslabs/aws-lambda-powertools-python/compare/v2.6.0...HEAD
+[v2.6.0]: https://github.com/awslabs/aws-lambda-powertools-python/compare/v2.5.0...v2.6.0
 [v2.5.0]: https://github.com/awslabs/aws-lambda-powertools-python/compare/v2.4.0...v2.5.0
 [v2.4.0]: https://github.com/awslabs/aws-lambda-powertools-python/compare/v2.3.1...v2.4.0
 [v2.3.1]: https://github.com/awslabs/aws-lambda-powertools-python/compare/v2.3.0...v2.3.1

aws_lambda_powertools/utilities/feature_flags/feature_flags.py

@@ -6,6 +6,11 @@
 from . import schema
 from .base import StoreProvider
 from .exceptions import ConfigurationStoreError
+from .time_conditions import (
+    compare_datetime_range,
+    compare_days_of_week,
+    compare_time_range,
+)
 
 
 class FeatureFlags:
@@ -59,6 +64,9 @@ def _match_by_action(self, action: str, condition_value: Any, context_value: Any
             schema.RuleAction.KEY_NOT_IN_VALUE.value: lambda a, b: a not in b,
             schema.RuleAction.VALUE_IN_KEY.value: lambda a, b: b in a,
             schema.RuleAction.VALUE_NOT_IN_KEY.value: lambda a, b: b not in a,
+            schema.RuleAction.SCHEDULE_BETWEEN_TIME_RANGE.value: lambda a, b: compare_time_range(a, b),
+            schema.RuleAction.SCHEDULE_BETWEEN_DATETIME_RANGE.value: lambda a, b: compare_datetime_range(a, b),
+            schema.RuleAction.SCHEDULE_BETWEEN_DAYS_OF_WEEK.value: lambda a, b: compare_days_of_week(a, b),
         }
 
         try:
@@ -83,10 +91,18 @@ def _evaluate_conditions(
             return False
 
         for condition in conditions:
-            context_value = context.get(str(condition.get(schema.CONDITION_KEY)))
+            context_value = context.get(condition.get(schema.CONDITION_KEY, ""))
             cond_action = condition.get(schema.CONDITION_ACTION, "")
             cond_value = condition.get(schema.CONDITION_VALUE)
 
+            # time based rule actions have no user context. the context is the condition key
+            if cond_action in (
+                schema.RuleAction.SCHEDULE_BETWEEN_TIME_RANGE.value,
+                schema.RuleAction.SCHEDULE_BETWEEN_DATETIME_RANGE.value,
+                schema.RuleAction.SCHEDULE_BETWEEN_DAYS_OF_WEEK.value,
+            ):
+                context_value = condition.get(schema.CONDITION_KEY)  # e.g., CURRENT_TIME
+
             if not self._match_by_action(action=cond_action, condition_value=cond_value, context_value=context_value):
                 self.logger.debug(
                     f"rule did not match action, rule_name={rule_name}, rule_value={rule_match_value}, "
@@ -228,7 +244,7 @@ def evaluate(self, *, name: str, context: Optional[Dict[str, Any]] = None, defau
         # method `get_matching_features` returning Dict[feature_name, feature_value]
         boolean_feature = feature.get(
             schema.FEATURE_DEFAULT_VAL_TYPE_KEY, True
-        )  # backwards compatability ,assume feature flag
+        )  # backwards compatibility, assume feature flag
         if not rules:
             self.logger.debug(
                 f"no rules found, returning feature default, name={name}, default={str(feat_default)}, boolean_feature={boolean_feature}"  # noqa: E501
@@ -287,7 +303,7 @@ def get_enabled_features(self, *, context: Optional[Dict[str, Any]] = None) -> L
             feature_default_value = feature.get(schema.FEATURE_DEFAULT_VAL_KEY)
             boolean_feature = feature.get(
                 schema.FEATURE_DEFAULT_VAL_TYPE_KEY, True
-            )  # backwards compatability ,assume feature flag
+            )  # backwards compatibility, assume feature flag
 
             if feature_default_value and not rules:
                 self.logger.debug(f"feature is enabled by default and has no defined rules, name={name}")

aws_lambda_powertools/utilities/feature_flags/schema.py

@@ -1,6 +1,10 @@
 import logging
+import re
+from datetime import datetime
 from enum import Enum
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from dateutil import tz
 
 from ... import Logger
 from .base import BaseValidator
@@ -14,9 +18,12 @@
 CONDITION_VALUE = "value"
 CONDITION_ACTION = "action"
 FEATURE_DEFAULT_VAL_TYPE_KEY = "boolean_type"
+TIME_RANGE_FORMAT = "%H:%M"  # hour:min 24 hours clock
+TIME_RANGE_RE_PATTERN = re.compile(r"2[0-3]:[0-5]\d|[0-1]\d:[0-5]\d")  # 24 hour clock
+HOUR_MIN_SEPARATOR = ":"
 
 
-class RuleAction(str, Enum):
+class RuleAction(Enum):
     EQUALS = "EQUALS"
     NOT_EQUALS = "NOT_EQUALS"
     KEY_GREATER_THAN_VALUE = "KEY_GREATER_THAN_VALUE"
@@ -31,6 +38,37 @@ class RuleAction(str, Enum):
     KEY_NOT_IN_VALUE = "KEY_NOT_IN_VALUE"
     VALUE_IN_KEY = "VALUE_IN_KEY"
     VALUE_NOT_IN_KEY = "VALUE_NOT_IN_KEY"
+    SCHEDULE_BETWEEN_TIME_RANGE = "SCHEDULE_BETWEEN_TIME_RANGE"  # hour:min 24 hours clock
+    SCHEDULE_BETWEEN_DATETIME_RANGE = "SCHEDULE_BETWEEN_DATETIME_RANGE"  # full datetime format, excluding timezone
+    SCHEDULE_BETWEEN_DAYS_OF_WEEK = "SCHEDULE_BETWEEN_DAYS_OF_WEEK"  # MONDAY, TUESDAY, .... see TimeValues enum
+
+
+class TimeKeys(Enum):
+    """
+    Possible keys when using time rules
+    """
+
+    CURRENT_TIME = "CURRENT_TIME"
+    CURRENT_DAY_OF_WEEK = "CURRENT_DAY_OF_WEEK"
+    CURRENT_DATETIME = "CURRENT_DATETIME"
+
+
+class TimeValues(Enum):
+    """
+    Possible values when using time rules
+    """
+
+    START = "START"
+    END = "END"
+    TIMEZONE = "TIMEZONE"
+    DAYS = "DAYS"
+    SUNDAY = "SUNDAY"
+    MONDAY = "MONDAY"
+    TUESDAY = "TUESDAY"
+    WEDNESDAY = "WEDNESDAY"
+    THURSDAY = "THURSDAY"
+    FRIDAY = "FRIDAY"
+    SATURDAY = "SATURDAY"
 
 
 class SchemaValidator(BaseValidator):
@@ -265,8 +303,132 @@ def validate_condition_key(condition: Dict[str, Any], rule_name: str):
         if not key or not isinstance(key, str):
             raise SchemaValidationError(f"'key' value must be a non empty string, rule={rule_name}")
 
+        # time actions need to have very specific keys
+        # SCHEDULE_BETWEEN_TIME_RANGE => CURRENT_TIME
+        # SCHEDULE_BETWEEN_DATETIME_RANGE => CURRENT_DATETIME
+        # SCHEDULE_BETWEEN_DAYS_OF_WEEK => CURRENT_DAY_OF_WEEK
+        action = condition.get(CONDITION_ACTION, "")
+        if action == RuleAction.SCHEDULE_BETWEEN_TIME_RANGE.value and key != TimeKeys.CURRENT_TIME.value:
+            raise SchemaValidationError(
+                f"'condition with a 'SCHEDULE_BETWEEN_TIME_RANGE' action must have a 'CURRENT_TIME' condition key, rule={rule_name}"  # noqa: E501
+            )
+        if action == RuleAction.SCHEDULE_BETWEEN_DATETIME_RANGE.value and key != TimeKeys.CURRENT_DATETIME.value:
+            raise SchemaValidationError(
+                f"'condition with a 'SCHEDULE_BETWEEN_DATETIME_RANGE' action must have a 'CURRENT_DATETIME' condition key, rule={rule_name}"  # noqa: E501
+            )
+        if action == RuleAction.SCHEDULE_BETWEEN_DAYS_OF_WEEK.value and key != TimeKeys.CURRENT_DAY_OF_WEEK.value:
+            raise SchemaValidationError(
+                f"'condition with a 'SCHEDULE_BETWEEN_DAYS_OF_WEEK' action must have a 'CURRENT_DAY_OF_WEEK' condition key, rule={rule_name}"  # noqa: E501
+            )
+
     @staticmethod
     def validate_condition_value(condition: Dict[str, Any], rule_name: str):
         value = condition.get(CONDITION_VALUE, "")
         if not value:
             raise SchemaValidationError(f"'value' key must not be empty, rule={rule_name}")
+        action = condition.get(CONDITION_ACTION, "")
+
+        # time actions need to be parsed to make sure date and time format is valid and timezone is recognized
+        if action == RuleAction.SCHEDULE_BETWEEN_TIME_RANGE.value:
+            ConditionsValidator._validate_schedule_between_time_and_datetime_ranges(
+                value, rule_name, action, ConditionsValidator._validate_time_value
+            )
+        elif action == RuleAction.SCHEDULE_BETWEEN_DATETIME_RANGE.value:
+            ConditionsValidator._validate_schedule_between_time_and_datetime_ranges(
+                value, rule_name, action, ConditionsValidator._validate_datetime_value
+            )
+        elif action == RuleAction.SCHEDULE_BETWEEN_DAYS_OF_WEEK.value:
+            ConditionsValidator._validate_schedule_between_days_of_week(value, rule_name)
+
+    @staticmethod
+    def _validate_datetime_value(datetime_str: str, rule_name: str):
+        date = None
+
+        # We try to parse first with timezone information in order to return the correct error messages
+        # when a timestamp with timezone is used. Otherwise, the user would get the first error "must be a valid
+        # ISO8601 time format" which is misleading
+
+        try:
+            # python < 3.11 don't support the Z timezone on datetime.fromisoformat,
+            # so we replace any Z with the equivalent "+00:00"
+            # datetime.fromisoformat is orders of magnitude faster than datetime.strptime
+            date = datetime.fromisoformat(datetime_str.replace("Z", "+00:00"))
+        except Exception:
+            raise SchemaValidationError(f"'START' and 'END' must be a valid ISO8601 time format, rule={rule_name}")
+
+        # we only allow timezone information to be set via the TIMEZONE field
+        # this way we can encode DST into the calculation. For instance, Copenhagen is
+        # UTC+2 during winter, and UTC+1 during summer, which would be impossible to define
+        # using a single ISO datetime string
+        if date.tzinfo is not None:
+            raise SchemaValidationError(
+                "'START' and 'END' must not include timezone information. Set the timezone using the 'TIMEZONE' "
+                f"field, rule={rule_name} "
+            )
+
+    @staticmethod
+    def _validate_time_value(time: str, rule_name: str):
+        # Using a regex instead of strptime because it's several orders of magnitude faster
+        match = TIME_RANGE_RE_PATTERN.match(time)
+
+        if not match:
+            raise SchemaValidationError(
+                f"'START' and 'END' must be a valid time format, time_format={TIME_RANGE_FORMAT}, rule={rule_name}"
+            )
+
+    @staticmethod
+    def _validate_schedule_between_days_of_week(value: Any, rule_name: str):
+        error_str = f"condition with a CURRENT_DAY_OF_WEEK action must have a condition value dictionary with 'DAYS' and 'TIMEZONE' (optional) keys, rule={rule_name}"  # noqa: E501
+        if not isinstance(value, dict):
+            raise SchemaValidationError(error_str)
+
+        days = value.get(TimeValues.DAYS.value)
+        if not isinstance(days, list) or not value:
+            raise SchemaValidationError(error_str)
+        for day in days:
+            if not isinstance(day, str) or day not in [
+                TimeValues.MONDAY.value,
+                TimeValues.TUESDAY.value,
+                TimeValues.WEDNESDAY.value,
+                TimeValues.THURSDAY.value,
+                TimeValues.FRIDAY.value,
+                TimeValues.SATURDAY.value,
+                TimeValues.SUNDAY.value,
+            ]:
+                raise SchemaValidationError(
+                    f"condition value DAYS must represent a day of the week in 'TimeValues' enum, rule={rule_name}"
+                )
+
+        timezone = value.get(TimeValues.TIMEZONE.value, "UTC")
+        if not isinstance(timezone, str):
+            raise SchemaValidationError(error_str)
+
+        # try to see if the timezone string corresponds to any known timezone
+        if not tz.gettz(timezone):
+            raise SchemaValidationError(f"'TIMEZONE' value must represent a valid IANA timezone, rule={rule_name}")
+
+    @staticmethod
+    def _validate_schedule_between_time_and_datetime_ranges(
+        value: Any, rule_name: str, action_name: str, validator: Callable[[str, str], None]
+    ):
+        error_str = f"condition with a '{action_name}' action must have a condition value type dictionary with 'START' and 'END' keys, rule={rule_name}"  # noqa: E501
+        if not isinstance(value, dict):
+            raise SchemaValidationError(error_str)
+
+        start_time = value.get(TimeValues.START.value)
+        end_time = value.get(TimeValues.END.value)
+        if not start_time or not end_time:
+            raise SchemaValidationError(error_str)
+        if not isinstance(start_time, str) or not isinstance(end_time, str):
+            raise SchemaValidationError(f"'START' and 'END' must be a non empty string, rule={rule_name}")
+
+        validator(start_time, rule_name)
+        validator(end_time, rule_name)
+
+        timezone = value.get(TimeValues.TIMEZONE.value, "UTC")
+        if not isinstance(timezone, str):
+            raise SchemaValidationError(f"'TIMEZONE' must be a string, rule={rule_name}")
+
+        # try to see if the timezone string corresponds to any known timezone
+        if not tz.gettz(timezone):
+            raise SchemaValidationError(f"'TIMEZONE' value must represent a valid IANA timezone, rule={rule_name}")