App Config Provider - Feature Flag Page based Etags (#46412)

* Feature Flag Page based Etags

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fixed review comments

* Adding check for more pages returning

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: mrm9084

sdk/appconfiguration/azure-appconfiguration-provider/CHANGELOG.md

@@ -13,6 +13,8 @@
 
 ### Other Changes
 
+- Switched feature flag refresh to use page-based etag checking instead of per-flag etag checking, reducing the number of requests needed to detect changes.
+
 ## 2.4.0 (2026-02-17)
 
 ### Features Added

sdk/appconfiguration/azure-appconfiguration-provider/assets.json

@@ -2,5 +2,5 @@
   "AssetsRepo": "Azure/azure-sdk-assets",
   "AssetsRepoPrefixPath": "python",
   "TagPrefix": "python/appconfiguration/azure-appconfiguration-provider",
-  "Tag": "python/appconfiguration/azure-appconfiguration-provider_b3a8244024"
+  "Tag": "python/appconfiguration/azure-appconfiguration-provider_34a63910b7"
 }

sdk/appconfiguration/azure-appconfiguration-provider/azure/appconfiguration/provider/_azureappconfigurationprovider.py

@@ -114,6 +114,7 @@ def _attempt_refresh(self, client: ConfigurationClient, replica_count: int, is_f
         updated_watched_settings: Mapping[Tuple[str, str], Optional[str]] = {}
         existing_feature_flag_usage = self._tracing_context.feature_filter_usage.copy()
         page_etags: List[List[str]] = []
+        feature_flag_page_etags: List[List[str]] = []
         try:
             if self._refresh_enabled and not self._watched_settings and self._refresh_timer.needs_refresh():
                 configuration_refresh_attempted = True
@@ -140,12 +141,12 @@ def _attempt_refresh(self, client: ConfigurationClient, replica_count: int, is_f
             if self._feature_flag_refresh_enabled and self._feature_flag_refresh_timer.needs_refresh():
                 feature_flag_refresh_attempted = True
 
-                feature_flags_need_refresh = client.try_check_feature_flags(
-                    self._watched_feature_flags, headers=headers, **kwargs
-                )
-
-                if feature_flags_need_refresh:
-                    feature_flags = client.load_feature_flags(self._feature_flag_selectors, headers=headers, **kwargs)
+                if not self._feature_flag_page_etags or client.check_feature_flag_page_etags(
+                    self._feature_flag_selectors, self._feature_flag_page_etags, headers=headers, **kwargs
+                ):
+                    feature_flags, feature_flag_page_etags = client.load_feature_flags(
+                        self._feature_flag_selectors, headers=headers, **kwargs
+                    )
 
             # Default to existing settings if no refresh occurred
             processed_settings = self._dict
@@ -162,6 +163,8 @@ def _attempt_refresh(self, client: ConfigurationClient, replica_count: int, is_f
                 self._page_etags = page_etags
                 # Update the watch keys that have changed
                 self._watched_settings.update(updated_watched_settings)
+            if feature_flags is not None:
+                self._feature_flag_page_etags = feature_flag_page_etags
             # Reset timers at the same time as they should load from the same store.
             if configuration_refresh_attempted:
                 self._refresh_timer.reset()
@@ -274,8 +277,10 @@ def _try_initialize(self, startup_exceptions: List[Exception], **kwargs: Any) ->
                 watched_settings = self._update_watched_settings(configuration_settings)
                 processed_settings = self._process_configurations(configuration_settings, client)
 
+                feature_flag_page_etags: List[List[str]] = []
                 if self._feature_flag_enabled:
-                    feature_flags: List[FeatureFlagConfigurationSetting] = client.load_feature_flags(
+                    feature_flags: List[FeatureFlagConfigurationSetting]
+                    feature_flags, feature_flag_page_etags = client.load_feature_flags(
                         self._feature_flag_selectors,
                         headers=headers,
                         **kwargs,
@@ -304,6 +309,7 @@ def _try_initialize(self, startup_exceptions: List[Exception], **kwargs: Any) ->
                     self._watched_settings = watched_settings
                     self._dict = processed_settings
                     self._page_etags = page_etags
+                    self._feature_flag_page_etags = feature_flag_page_etags
                 return True
             except AzureError as e:
                 logger.warning("Failed to load configurations from endpoint %s.\n %s", client.endpoint, e.message)
@@ -371,9 +377,6 @@ def _process_configurations(
                 # Feature flags are not processed like other settings
                 feature_flag_value = self._process_feature_flag(setting)
                 feature_flags_processed.append(feature_flag_value)
-
-                if self._feature_flag_refresh_enabled:
-                    self._watched_feature_flags[(setting.key, setting.label)] = setting.etag
             else:
                 key = self._process_key_name(setting)
                 value = self._process_key_value(setting)

sdk/appconfiguration/azure-appconfiguration-provider/azure/appconfiguration/provider/_azureappconfigurationproviderbase.py

@@ -105,7 +105,6 @@ def __init__(self, **kwargs: Any) -> None:
         self._feature_flag_selectors = kwargs.pop("feature_flag_selectors", None)
         if self._feature_flag_selectors is None:
             self._feature_flag_selectors = [SettingSelector(key_filter="*")]
-        self._watched_feature_flags: Dict[Tuple[str, str], Optional[str]] = {}
         self._feature_flag_refresh_timer: _RefreshTimer = _RefreshTimer(**kwargs)
         self._feature_flag_refresh_enabled = kwargs.pop("feature_flag_refresh_enabled", False)
         refresh_enabled = kwargs.pop("refresh_enabled", None)
@@ -115,6 +114,7 @@ def __init__(self, **kwargs: Any) -> None:
             refresh_enabled = True
         self._refresh_enabled = refresh_enabled
         self._page_etags: List[List[str]] = []
+        self._feature_flag_page_etags: List[List[str]] = []
         self._tracing_context = _RequestTracingContext(kwargs.pop("load_balancing_enabled", False))
         self._update_lock = Lock()
         self._refresh_lock = Lock()
@@ -374,7 +374,6 @@ def _process_feature_flags(
             # Reset feature flag usage
             self._tracing_context.reset_feature_filter_usage()
             processed_feature_flags = [self._process_feature_flag(ff) for ff in feature_flags]
-            self._watched_feature_flags = self._update_watched_feature_flags(feature_flags)
 
         if self._feature_flag_enabled:
             processed_settings[FEATURE_MANAGEMENT_KEY] = {}
@@ -406,20 +405,6 @@ def _update_watched_settings(
                 watched_settings[(config.key, config.label)] = config.etag
         return watched_settings
 
-    def _update_watched_feature_flags(
-        self, feature_flags: List[FeatureFlagConfigurationSetting]
-    ) -> Dict[Tuple[str, str], Optional[str]]:
-        """
-        Updates the etags of watched feature flags that are part of the configuration
-        :param List[FeatureFlagConfigurationSetting] feature_flags: The list of feature flags to update
-        :return: A dictionary mapping (key, label) tuples to their updated etags
-        :rtype: Dict[Tuple[str, str], Optional[str]]
-        """
-        watched_feature_flags: Dict[Tuple[str, str], Optional[str]] = {}
-        for feature_flag in feature_flags:
-            watched_feature_flags[(feature_flag.key, feature_flag.label)] = feature_flag.etag
-        return watched_feature_flags
-
     def _update_correlation_context_header(
         self,
         headers: Dict[str, str],

sdk/appconfiguration/azure-appconfiguration-provider/azure/appconfiguration/provider/_client_manager.py

@@ -187,6 +187,9 @@ def check_page_etags(self, selects: List[SettingSelector], page_etags: List[List
         :rtype: bool
         """
         for i, select in enumerate(selects):
+            if i >= len(page_etags):
+                # Missing or stale etag state should trigger a refresh instead of failing.
+                return True
             selector_etags = page_etags[i]
             if select.snapshot_name is None:
                 # We only process non-snapshot selectors here, because snapshot never change
@@ -204,17 +207,30 @@ def check_page_etags(self, selects: List[SettingSelector], page_etags: List[List
     @distributed_trace
     def load_feature_flags(
         self, feature_flag_selectors: List[SettingSelector], **kwargs
-    ) -> List[FeatureFlagConfigurationSetting]:
+    ) -> Tuple[List[FeatureFlagConfigurationSetting], List[List[str]]]:
+        """
+        Loads feature flags using page-based iteration, collecting page etags for each selector.
+
+        :param feature_flag_selectors: List of setting selectors to filter feature flags
+        :type feature_flag_selectors: List[SettingSelector]
+        :return: A tuple of (feature_flags, page_etags_per_selector)
+        :rtype: Tuple[List[FeatureFlagConfigurationSetting], List[List[str]]]
+        """
         loaded_feature_flags: List[FeatureFlagConfigurationSetting] = []
+        page_etags: List[List[str]] = []
         # Needs to be removed unknown keyword argument for list_configuration_settings
         kwargs.pop("sentinel_keys", None)
         for select in feature_flag_selectors:
-            feature_flags = []
+            selector_etags: List[str] = []
             if select.snapshot_name is not None:
                 # When loading from a snapshot, ignore key_filter, label_filter, and tag_filters
                 if not self._validate_snapshot(select.snapshot_name):
-                    return []
+                    page_etags.append(selector_etags)
+                    continue
                 feature_flags = self._client.list_configuration_settings(snapshot_name=select.snapshot_name, **kwargs)
+                for ff in feature_flags:
+                    if isinstance(ff, FeatureFlagConfigurationSetting):
+                        loaded_feature_flags.append(ff)
             else:
                 # Handle None key_filter by converting to empty string
                 key_filter = select.key_filter if select.key_filter is not None else ""
@@ -224,9 +240,47 @@ def load_feature_flags(
                     tags_filter=select.tag_filters,
                     **kwargs,
                 )
-            loaded_feature_flags.extend(ff for ff in feature_flags if isinstance(ff, FeatureFlagConfigurationSetting))
+                iterator = feature_flags.by_page()
+                for page in iterator:
+                    for ff in page:
+                        if isinstance(ff, FeatureFlagConfigurationSetting):
+                            loaded_feature_flags.append(ff)
+                    selector_etags.append(iterator.etag)
+            page_etags.append(selector_etags)
 
-        return loaded_feature_flags
+        return loaded_feature_flags, page_etags
+
+    @distributed_trace
+    def check_feature_flag_page_etags(
+        self, feature_flag_selectors: List[SettingSelector], page_etags: List[List[str]], **kwargs
+    ) -> bool:
+        """
+        Checks if any feature flag page has changed using page etags.
+
+        :param feature_flag_selectors: List of setting selectors for feature flags
+        :type feature_flag_selectors: List[SettingSelector]
+        :param page_etags: The page etags from the last load, one list per selector
+        :type page_etags: List[List[str]]
+        :return: True if any page has changed, False otherwise
+        :rtype: bool
+        """
+        for i, select in enumerate(feature_flag_selectors):
+            if i >= len(page_etags):
+                # Missing or stale etag state should trigger a refresh instead of failing.
+                return True
+            selector_etags = page_etags[i]
+            if select.snapshot_name is None:
+                key_filter = select.key_filter if select.key_filter is not None else ""
+                feature_flags = self._client.list_configuration_settings(
+                    key_filter=FEATURE_FLAG_PREFIX + key_filter,
+                    label_filter=select.label_filter,
+                    tags_filter=select.tag_filters,
+                    **kwargs,
+                )
+                for _ in feature_flags.by_page(match_conditions=selector_etags):
+                    # If any page is returned, it means that page has changed
+                    return True
+        return False
 
     @distributed_trace
     def get_updated_watched_settings(
@@ -258,25 +312,6 @@ def get_updated_watched_settings(
             return updated_watched_settings
         return {}
 
-    @distributed_trace
-    def try_check_feature_flags(
-        self, watched_feature_flags: Mapping[Tuple[str, str], Optional[str]], headers: Dict[str, str], **kwargs
-    ) -> bool:
-        """
-        Gets the refreshed feature flags if they have changed.
-
-        :param Mapping[Tuple[str, str], Optional[str]] watched_feature_flags: The feature flags to check for changes
-        :param Mapping[str, str] headers: The headers to use for the request
-
-        :return: True if any feature flags have changed, False otherwise
-        :rtype: bool
-        """
-        for (key, label), etag in watched_feature_flags.items():
-            changed, _ = self._check_configuration_setting(key=key, label=label, etag=etag, headers=headers, **kwargs)
-            if changed:
-                return True
-        return False
-
     @distributed_trace
     def get_configuration_setting(self, key: str, label: str, **kwargs) -> Optional[ConfigurationSetting]:
         """

sdk/appconfiguration/azure-appconfiguration-provider/azure/appconfiguration/provider/aio/_async_client_manager.py

@@ -10,7 +10,6 @@
 from typing import Tuple, Union, Dict, List, Optional, Mapping, TYPE_CHECKING
 from typing_extensions import Self
 from azure.core import MatchConditions
-from azure.core.async_paging import AsyncItemPaged
 from azure.core.tracing.decorator import distributed_trace
 from azure.core.exceptions import HttpResponseError
 from azure.appconfiguration import (  # type:ignore # pylint:disable=no-name-in-module
@@ -190,6 +189,9 @@ async def check_page_etags(self, selects: List[SettingSelector], page_etags: Lis
         :rtype: bool
         """
         for i, select in enumerate(selects):
+            if i >= len(page_etags):
+                # Missing or stale etag state should trigger a refresh instead of failing.
+                return True
             selector_etags = page_etags[i]
             if select.snapshot_name is None:
                 # We only process non-snapshot selectors here, because snapshot never change
@@ -207,17 +209,30 @@ async def check_page_etags(self, selects: List[SettingSelector], page_etags: Lis
     @distributed_trace
     async def load_feature_flags(
         self, feature_flag_selectors: List[SettingSelector], **kwargs
-    ) -> List[FeatureFlagConfigurationSetting]:
+    ) -> Tuple[List[FeatureFlagConfigurationSetting], List[List[str]]]:
+        """
+        Loads feature flags using page-based iteration, collecting page etags for each selector.
+
+        :param feature_flag_selectors: List of setting selectors to filter feature flags
+        :type feature_flag_selectors: List[SettingSelector]
+        :return: A tuple of (feature_flags, page_etags_per_selector)
+        :rtype: Tuple[List[FeatureFlagConfigurationSetting], List[List[str]]]
+        """
         loaded_feature_flags: List[FeatureFlagConfigurationSetting] = []
+        page_etags: List[List[str]] = []
         # Needs to be removed unknown keyword argument for list_configuration_settings
         kwargs.pop("sentinel_keys", None)
         for select in feature_flag_selectors:
-            feature_flags: AsyncItemPaged[ConfigurationSetting]
+            selector_etags: List[str] = []
             if select.snapshot_name is not None:
                 # When loading from a snapshot, ignore key_filter, label_filter, and tag_filters
                 if not await self._validate_snapshot(select.snapshot_name):
-                    return []
+                    page_etags.append(selector_etags)
+                    continue
                 feature_flags = self._client.list_configuration_settings(snapshot_name=select.snapshot_name, **kwargs)
+                async for ff in feature_flags:
+                    if isinstance(ff, FeatureFlagConfigurationSetting):
+                        loaded_feature_flags.append(ff)
             else:
                 # Handle None key_filter by converting to empty string
                 key_filter = select.key_filter if select.key_filter is not None else ""
@@ -227,11 +242,47 @@ async def load_feature_flags(
                     tags_filter=select.tag_filters,
                     **kwargs,
                 )
-            loaded_feature_flags.extend(
-                [ff async for ff in feature_flags if isinstance(ff, FeatureFlagConfigurationSetting)]
-            )
+                iterator = feature_flags.by_page()
+                async for page in iterator:
+                    async for ff in page:
+                        if isinstance(ff, FeatureFlagConfigurationSetting):
+                            loaded_feature_flags.append(ff)
+                    selector_etags.append(iterator.etag)  # type: ignore[attr-defined]
+            page_etags.append(selector_etags)
+
+        return loaded_feature_flags, page_etags
 
-        return loaded_feature_flags
+    @distributed_trace
+    async def check_feature_flag_page_etags(
+        self, feature_flag_selectors: List[SettingSelector], page_etags: List[List[str]], **kwargs
+    ) -> bool:
+        """
+        Checks if any feature flag page has changed using page etags.
+
+        :param feature_flag_selectors: List of setting selectors for feature flags
+        :type feature_flag_selectors: List[SettingSelector]
+        :param page_etags: The page etags from the last load, one list per selector
+        :type page_etags: List[List[str]]
+        :return: True if any page has changed, False otherwise
+        :rtype: bool
+        """
+        for i, select in enumerate(feature_flag_selectors):
+            if i >= len(page_etags):
+                # Missing or stale etag state should trigger a refresh instead of failing.
+                return True
+            selector_etags = page_etags[i]
+            if select.snapshot_name is None:
+                key_filter = select.key_filter if select.key_filter is not None else ""
+                feature_flags = self._client.list_configuration_settings(
+                    key_filter=FEATURE_FLAG_PREFIX + key_filter,
+                    label_filter=select.label_filter,
+                    tags_filter=select.tag_filters,
+                    **kwargs,
+                )
+                async for _ in feature_flags.by_page(match_conditions=selector_etags):  # type: ignore[call-arg]
+                    # If any page is returned, it means that page has changed
+                    return True
+        return False
 
     @distributed_trace
     async def get_updated_watched_settings(
@@ -263,27 +314,6 @@ async def get_updated_watched_settings(
             return updated_watched_settings
         return {}
 
-    @distributed_trace
-    async def try_check_feature_flags(
-        self, watched_feature_flags: Mapping[Tuple[str, str], Optional[str]], headers: Dict[str, str], **kwargs
-    ) -> bool:
-        """
-        Gets the refreshed feature flags if they have changed.
-
-        :param Mapping[Tuple[str, str], Optional[str]] watched_feature_flags: The feature flags to check for changes
-        :param Mapping[str, str] headers: The headers to use for the request
-
-        :return: True if any feature flags have changed, False otherwise
-        :rtype: bool
-        """
-        for (key, label), etag in watched_feature_flags.items():
-            changed, _ = await self._check_configuration_setting(
-                key=key, label=label, etag=etag, headers=headers, **kwargs
-            )
-            if changed:
-                return True
-        return False
-
     @distributed_trace
     async def get_configuration_setting(self, key: str, label: str, **kwargs) -> Optional[ConfigurationSetting]:
         """