feat(feature_flags): Add Time based feature flags actions

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}, "
@@ -169,7 +185,7 @@ def get_configuration(self) -> Dict:
         # parse result conf as JSON, keep in cache for max age defined in store
         self.logger.debug(f"Fetching schema from registered store, store={self.store}")
         config: Dict = self.store.get_configuration()
-        validator = schema.SchemaValidator(schema=config)
+        validator = schema.SchemaValidator(schema=config, logger=self.logger)
         validator.validate()
 
         return config
@@ -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):
@@ -143,7 +181,7 @@ def validate(self) -> None:
         if not isinstance(self.schema, dict):
             raise SchemaValidationError(f"Features must be a dictionary, schema={str(self.schema)}")
 
-        features = FeaturesValidator(schema=self.schema)
+        features = FeaturesValidator(schema=self.schema, logger=self.logger)
         features.validate()
 
 
@@ -158,7 +196,7 @@ def validate(self):
         for name, feature in self.schema.items():
             self.logger.debug(f"Attempting to validate feature '{name}'")
             boolean_feature: bool = self.validate_feature(name, feature)
-            rules = RulesValidator(feature=feature, boolean_feature=boolean_feature)
+            rules = RulesValidator(feature=feature, boolean_feature=boolean_feature, logger=self.logger)
             rules.validate()
 
     # returns True in case the feature is a regular feature flag with a  boolean default value
@@ -196,14 +234,15 @@ def validate(self):
             return
 
         if not isinstance(self.rules, dict):
+            self.logger.debug(f"Feature rules must be a dictionary, feature={self.feature_name}")
             raise SchemaValidationError(f"Feature rules must be a dictionary, feature={self.feature_name}")
 
         for rule_name, rule in self.rules.items():
-            self.logger.debug(f"Attempting to validate rule '{rule_name}'")
+            self.logger.debug(f"Attempting to validate rule={rule_name} and feature={self.feature_name}")
             self.validate_rule(
                 rule=rule, rule_name=rule_name, feature_name=self.feature_name, boolean_feature=self.boolean_feature
             )
-            conditions = ConditionsValidator(rule=rule, rule_name=rule_name)
+            conditions = ConditionsValidator(rule=rule, rule_name=rule_name, logger=self.logger)
             conditions.validate()
 
     @staticmethod
@@ -233,12 +272,14 @@ def __init__(self, rule: Dict[str, Any], rule_name: str, logger: Optional[Union[
         self.logger = logger or logging.getLogger(__name__)
 
     def validate(self):
+
         if not self.conditions or not isinstance(self.conditions, list):
+            self.logger.debug(f"Condition is empty or invalid for rule={self.rule_name}")
             raise SchemaValidationError(f"Invalid condition, rule={self.rule_name}")
 
         for condition in self.conditions:
             # Condition can contain PII data; do not log condition value
-            self.logger.debug(f"Attempting to validate condition for '{self.rule_name}'")
+            self.logger.debug(f"Attempting to validate condition for {self.rule_name}")
             self.validate_condition(rule_name=self.rule_name, condition=condition)
 
     @staticmethod
@@ -265,8 +306,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}")

aws_lambda_powertools/utilities/feature_flags/time_conditions.py

@@ -0,0 +1,73 @@
+from datetime import datetime, tzinfo
+from typing import Dict, Optional
+
+from dateutil.tz import gettz
+
+from .schema import HOUR_MIN_SEPARATOR, TimeValues
+
+
+def _get_now_from_timezone(timezone: Optional[tzinfo]) -> datetime:
+    """
+    Returns now in the specified timezone. Defaults to UTC if not present.
+    At this stage, we already validated that the passed timezone string is valid, so we assume that
+    gettz() will return a tzinfo object.
+    """
+    timezone = gettz("UTC") if timezone is None else timezone
+    return datetime.now(timezone)
+
+
+def compare_days_of_week(action: str, values: Dict) -> bool:
+    timezone_name = values.get(TimeValues.TIMEZONE.value, "UTC")
+
+    # %A = Weekday as locale’s full name.
+    current_day = _get_now_from_timezone(gettz(timezone_name)).strftime("%A").upper()
+
+    days = values.get(TimeValues.DAYS.value, [])
+    return current_day in days
+
+
+def compare_datetime_range(action: str, values: Dict) -> bool:
+    timezone_name = values.get(TimeValues.TIMEZONE.value, "UTC")
+    timezone = gettz(timezone_name)
+    current_time: datetime = _get_now_from_timezone(timezone)
+
+    start_date_str = values.get(TimeValues.START.value, "")
+    end_date_str = values.get(TimeValues.END.value, "")
+
+    # Since start_date and end_date doesn't include timezone information, we mark the timestamp
+    # with the same timezone as the current_time. This way all the 3 timestamps will be on
+    # the same timezone.
+    start_date = datetime.fromisoformat(start_date_str).replace(tzinfo=timezone)
+    end_date = datetime.fromisoformat(end_date_str).replace(tzinfo=timezone)
+    return start_date <= current_time <= end_date
+
+
+def compare_time_range(action: str, values: Dict) -> bool:
+    timezone_name = values.get(TimeValues.TIMEZONE.value, "UTC")
+    current_time: datetime = _get_now_from_timezone(gettz(timezone_name))
+
+    start_hour, start_min = values.get(TimeValues.START.value, "").split(HOUR_MIN_SEPARATOR)
+    end_hour, end_min = values.get(TimeValues.END.value, "").split(HOUR_MIN_SEPARATOR)
+
+    start_time = current_time.replace(hour=int(start_hour), minute=int(start_min))
+    end_time = current_time.replace(hour=int(end_hour), minute=int(end_min))
+
+    if int(end_hour) < int(start_hour):
+        # When the end hour is smaller than start hour, it means we are crossing a day's boundary.
+        # In this case we need to assert that current_time is **either** on one side or the other side of the boundary
+        #
+        # ┌─────┐                                    ┌─────┐                                  ┌─────┐
+        # │20.00│                                    │00.00│                                  │04.00│
+        # └─────┘                                    └─────┘                                  └─────┘
+        #    ───────────────────────────────────────────┬─────────────────────────────────────────▶
+        #    ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─  │ ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
+        #                                             │ │                                        │
+        #    │           either this area               │ │             or this area
+        #                                             │ │                                        │
+        #    └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─  │ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
+        #                                               │
+
+        return (start_time <= current_time) or (current_time <= end_time)
+    else:
+        # In normal circumstances, we need to assert **both** conditions
+        return start_time <= current_time <= end_time