Add cold-start metadata cache cross-region hedging (port of dotnet #5923)

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

Author: Copilot

sdk/cosmos/azure-cosmos/CHANGELOG.md

@@ -3,6 +3,7 @@
 ### 4.16.2 (Unreleased)
 
 #### Features Added
+* Added cold-start metadata cache cross-region hedging. When enabled, the SDK hedges the first-time population of the container and partition-key-range metadata caches to a second region if the primary region is slow, returning the first acceptable response. Controlled by the new `enable_metadata_hedging_for_cold_start` client keyword (tri-state: `None` follows the account's PPAF state, `True` forces it on, `False` disables it).
 
 #### Breaking Changes
 

sdk/cosmos/azure-cosmos/azure/cosmos/_availability_strategy_config.py

@@ -27,14 +27,22 @@
 DEFAULT_THRESHOLD_MS = 500
 DEFAULT_THRESHOLD_STEPS_MS = 100
 
+# Defaults for cold-start metadata cache hedging. These are SDK-derived and not
+# customer-configurable. The threshold mirrors the .NET design (first-attempt
+# control-plane timeout ~1s + a 500ms step => 1500ms). The concurrency budget
+# caps the number of in-flight metadata hedges per client.
+DEFAULT_METADATA_HEDGING_THRESHOLD_MS = 1500
+DEFAULT_METADATA_HEDGING_THRESHOLD_STEPS_MS = 500
+DEFAULT_METADATA_HEDGING_CONCURRENCY_BUDGET = 8
+
 
 class CrossRegionHedgingStrategy:
     """Configuration for cross-region request hedging strategy.
 
     :param config: Dictionary containing configuration values, defaults to None
     :type config: Optional[Dict[str, Any]]
     :raises ValueError: If configuration values are invalid
-    
+
     The config dictionary can contain:
     - threshold_ms: Time in ms before routing to alternate region (default: 500)
     - threshold_steps_ms: Time interval between routing attempts (default: 100)
@@ -53,11 +61,49 @@ def __init__(self, config: Optional[dict[str, Any]] = None) -> None:
             raise ValueError("threshold_steps_ms must be positive")
 
 
+class MetadataCrossRegionHedgingStrategy(CrossRegionHedgingStrategy):
+    """Cold-start metadata cache cross-region hedging configuration.
+
+    Unlike :class:`CrossRegionHedgingStrategy`, the metadata hedging threshold is a
+    fixed, SDK-derived value and is not customer-configurable. The strategy is bounded
+    to the primary request plus a single cross-region hedge.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            {
+                "threshold_ms": DEFAULT_METADATA_HEDGING_THRESHOLD_MS,
+                "threshold_steps_ms": DEFAULT_METADATA_HEDGING_THRESHOLD_STEPS_MS,
+            }
+        )
+
+
+def resolve_metadata_hedging_opt_in(opt_in: Optional[bool], ppaf_enabled: bool) -> bool:
+    """Resolve the tri-state cold-start metadata hedging opt-in to a concrete bool.
+
+    When the customer leaves the opt-in ``None`` (the default), cold-start metadata
+    hedging follows the account's PPAF (Per-Partition Automatic Failover) state: it is
+    enabled when PPAF is enabled and disabled otherwise. An explicit ``True`` enables
+    hedging even when PPAF is disabled, and an explicit ``False`` disables it regardless
+    of PPAF.
+
+    :param opt_in: The customer-supplied tri-state opt-in (True/False/None).
+    :type opt_in: Optional[bool]
+    :param ppaf_enabled: Whether Per-Partition Automatic Failover is enabled for the account.
+    :type ppaf_enabled: bool
+    :returns: True if cold-start metadata hedging should be applied, False otherwise.
+    :rtype: bool
+    """
+    if opt_in is None:
+        return ppaf_enabled
+    return opt_in
+
+
 def _validate_request_hedging_strategy(
         config: Optional[Union[bool, dict[str, Any]]]
 ) -> Union[CrossRegionHedgingStrategy, bool, None]:
     """Validate and create a CrossRegionHedgingStrategy for a request.
-    
+
     :param config: Configuration for availability strategy. Can be:
         - None: Returns None (no strategy, uses client default if available)
         - True: Returns strategy with default values (threshold_ms=500, threshold_steps_ms=100)

sdk/cosmos/azure-cosmos/azure/cosmos/_cosmos_client_connection.py

@@ -62,6 +62,7 @@
 from . import http_constants, exceptions
 from ._auth_policy import CosmosBearerTokenCredentialPolicy
 from ._availability_strategy_config import validate_client_hedging_strategy, CrossRegionHedgingStrategy
+from ._metadata_hedging import MetadataCrossRegionHedgingHandler
 from ._base import _build_properties_cache
 from ._change_feed.change_feed_iterable import ChangeFeedIterable
 from ._change_feed.change_feed_state import ChangeFeedState
@@ -143,6 +144,7 @@ def __init__( # pylint: disable=too-many-statements
         consistency_level: Optional[str] = None,
         availability_strategy: Union[bool, dict[str, Any]] = False,
         availability_strategy_executor: Optional[ThreadPoolExecutor] = None,
+        enable_metadata_hedging_for_cold_start: Optional[bool] = None,
         **kwargs: Any
     ) -> None:
         """
@@ -170,6 +172,12 @@ def __init__( # pylint: disable=too-many-statements
         self.availability_strategy: Union[CrossRegionHedgingStrategy, None] =\
             validate_client_hedging_strategy(availability_strategy)
         self.availability_strategy_executor: Optional[ThreadPoolExecutor] = availability_strategy_executor
+        # Tri-state opt-in for cold-start metadata cache cross-region hedging. None follows the
+        # account's PPAF state, True forces it on, False disables it (no handler is created).
+        self._metadata_hedging_opt_in: Optional[bool] = enable_metadata_hedging_for_cold_start
+        self._metadata_hedging_handler: Optional[MetadataCrossRegionHedgingHandler] = (
+            None if enable_metadata_hedging_for_cold_start is False else MetadataCrossRegionHedgingHandler()
+        )
         self.master_key: Optional[str] = None
 
         self.resource_tokens: Optional[Mapping[str, Any]] = None