chore: support non UTC timestamps everywhere

Author: rubenfonseca

aws_lambda_powertools/utilities/feature_flags/feature_flags.py

@@ -7,9 +7,9 @@
 from .base import StoreProvider
 from .exceptions import ConfigurationStoreError
 from .time_conditions import (
-    compare_utc_datetime_range,
-    compare_utc_days_of_week,
-    compare_utc_time_range,
+    compare_datetime_range,
+    compare_days_of_week,
+    compare_time_range,
 )
 
 
@@ -64,9 +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_utc_time_range(a, b),
-            schema.RuleAction.SCHEDULE_BETWEEN_DATETIME_RANGE.value: lambda a, b: compare_utc_datetime_range(a, b),
-            schema.RuleAction.SCHEDULE_BETWEEN_DAYS_OF_WEEK.value: lambda a, b: compare_utc_days_of_week(a, b),
+            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:
@@ -101,7 +101,7 @@ def _evaluate_conditions(
                 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_UTC
+                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(

aws_lambda_powertools/utilities/feature_flags/schema.py

@@ -4,6 +4,8 @@
 from enum import Enum
 from typing import Any, Callable, Dict, List, Optional, Union
 
+from dateutil import tz
+
 from ... import Logger
 from .base import BaseValidator
 from .exceptions import SchemaValidationError
@@ -42,14 +44,16 @@ class RuleAction(Enum):
 
 
 class TimeKeys(Enum):
-    CURRENT_TIME_UTC = "CURRENT_TIME_UTC"
-    CURRENT_DAY_OF_WEEK_UTC = "CURRENT_DAY_OF_WEEK_UTC"
-    CURRENT_DATETIME_UTC = "CURRENT_DATETIME_UTC"
+    CURRENT_TIME = "CURRENT_TIME"
+    CURRENT_DAY_OF_WEEK = "CURRENT_DAY_OF_WEEK"
+    CURRENT_DATETIME = "CURRENT_DATETIME"
 
 
 class TimeValues(Enum):
     START = "START"
     END = "END"
+    TIMEZONE = "TIMEZONE"
+    DAYS = "DAYS"
     SUNDAY = "SUNDAY"
     MONDAY = "MONDAY"
     TUESDAY = "TUESDAY"
@@ -291,17 +295,17 @@ 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}")
         action = condition.get(CONDITION_ACTION, "")
-        if action == RuleAction.SCHEDULE_BETWEEN_TIME_RANGE.value and key != TimeKeys.CURRENT_TIME_UTC.value:
+        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_UTC' condition key, rule={rule_name}"  # noqa: E501
+                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_UTC.value:
+        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_UTC' condition key, rule={rule_name}"  # noqa: E501
+                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_UTC.value:
+        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_UTC' condition key, rule={rule_name}"  # noqa: E501
+                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
@@ -324,13 +328,25 @@ def validate_condition_value(condition: Dict[str, Any], rule_name: str):
 
     @staticmethod
     def _validate_datetime_value(datetime_str: str, rule_name: str):
+        date = None
+
         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(datetime_str.replace("Z", "+00:00"))
+            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
@@ -343,11 +359,14 @@ def _validate_time_value(time: str, rule_name: str):
 
     @staticmethod
     def _validate_schedule_between_days_of_week(value: Any, rule_name: str):
-        if not isinstance(value, list) or not value:
-            raise SchemaValidationError(
-                f"condition with a CURRENT_DAY_OF_WEEK_UTC action must have a non empty condition value type list, rule={rule_name}"  # noqa: E501
-            )
-        for day in value:
+        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,
@@ -358,9 +377,15 @@ def _validate_schedule_between_days_of_week(value: Any, rule_name: str):
                 TimeValues.SUNDAY.value,
             ]:
                 raise SchemaValidationError(
-                    f"condition value must represent a day of the week in 'TimeValues' enum, rule={rule_name}"
+                    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)
+        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]
@@ -376,3 +401,9 @@ def _validate_schedule_between_time_and_datetime_ranges(
             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}")
+        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

@@ -1,38 +1,49 @@
-from datetime import datetime, timezone
-from typing import Dict, List
+from datetime import datetime, tzinfo
+from typing import Dict, Optional
+
+from dateutil.tz import gettz
 
 from .schema import HOUR_MIN_SEPARATOR, TimeValues
 
 
-def _get_utc_time_now() -> datetime:
-    return datetime.now(timezone.utc)
+def _get_now_from_timezone(timezone: Optional[tzinfo]) -> datetime:
+    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")
+    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_utc_days_of_week(action: str, values: List[str]) -> bool:
-    current_day = _get_utc_time_now().strftime("%A").upper()
-    return current_day in values
 
+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)
 
-def compare_utc_datetime_range(action: str, values: Dict) -> bool:
-    current_time_utc: datetime = _get_utc_time_now()
+    start_date_str = values.get(TimeValues.START.value, "")
+    end_date_str = values.get(TimeValues.END.value, "")
 
-    # python < 3.11 don't support Z as a timezone on datetime.fromisoformat,
-    # so we replace any Z with the equivalent "+00:00
-    start_date_str = values.get(TimeValues.START.value, "").replace("Z", "+00:00")
-    end_date_str = values.get(TimeValues.END.value, "").replace("Z", "+00:00")
+    # Since start_date and end_date don'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
 
-    start_date = datetime.fromisoformat(start_date_str)
-    end_date = datetime.fromisoformat(end_date_str)
-    return start_date <= current_time_utc <= 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))
 
-def compare_utc_time_range(action: str, values: Dict) -> bool:
-    current_time_utc: datetime = _get_utc_time_now()
     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)
     return (
-        current_time_utc.hour >= int(start_hour)
-        and current_time_utc.hour <= int(end_hour)
-        and current_time_utc.minute >= int(start_min)
-        and current_time_utc.minute <= int(end_min)
+        current_time.hour >= int(start_hour)
+        and current_time.hour <= int(end_hour)
+        and current_time.minute >= int(start_min)
+        and current_time.minute <= int(end_min)
     )