removeTypeRequirementFromAvailabilityStrategyConfig (#44190)

* remove type requirment from availability_strategy_config

---------

Co-authored-by: annie-mac <[email protected]>
Co-authored-by: Simon Moreno <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 4 people

sdk/cosmos/azure-cosmos/README.md

@@ -945,6 +945,84 @@ Per partition automatic failover enables the SDK to automatically redirect write
 only for single write region accounts that have at least one read-only region. When per partition automatic failover is enabled, per partition circuit breaker and cross-region hedging is enabled by default, meaning 
 all its configurable options also apply to per partition automatic failover. To enable this feature, follow the guide [here](https://learn.microsoft.com/azure/cosmos-db/how-to-configure-per-partition-automatic-failover).
 
+### Cross Region Hedging Availability Strategy
+
+Cross region hedging availability strategy improves availability and reduces latency by sending duplicate requests to secondary regions if the primary region is slow or unavailable. The SDK uses the first successful response, helping to mitigate regional outages or high latency.
+
+#### Key Concepts
+
+- **Hedged Requests**: The SDK sends a parallel request to another region if the primary region does not respond within a configured delay.
+- **Configurable**: Hedging can be enabled or disabled, and the delay before sending a hedged request is tunable.
+- **ThreadPoolExecutor**: The sync CosmosClient instance will use a ThreadPoolExecutor under the hood for parallelizing requests. Users can choose whether to use the default ThreadPoolExecutor the SDK uses, or to pass in their own instance. *The async client does not need the executor since it uses asynchronous logic to parallelize requests.*
+
+#### Enabling Cross Region Hedging
+
+You can enable cross region hedging by passing the `availability_strategy_config` parameter as a dictionary to the `CosmosClient` or per-request. The most common configuration keys are `threshold_ms` (delay before sending a hedged request) and `threshold_steps_ms` (step interval for additional hedged requests).
+
+#### Client-level configuration
+
+```python
+from azure.cosmos import CosmosClient
+
+client = CosmosClient(
+    "<account-uri>",
+    "<account-key>",
+    availability_strategy_config={"threshold_ms": 150, "threshold_steps_ms": 50}
+)
+```
+
+#### Request-level configuration
+
+```python
+# Override or provide the strategy per request
+container.read_item(
+    item="item_id",
+    partition_key="pk_value",
+    availability_strategy_config={"threshold_ms": 150, "threshold_steps_ms": 50}
+)
+```
+
+#### Disable availability strategy on request level
+
+```python
+# Disable cross region hedging for a specific request, even if enabled at client level
+container.read_item(
+    item="item_id",
+    partition_key="pk_value",
+    availability_strategy_config=None
+)
+```
+
+#### Customized executor for hedging for sync client
+
+```python
+# Pass in your own custom TheadPoolExecutor to use with the sync client
+from concurrent.futures import ThreadPoolExecutor
+from azure.cosmos import CosmosClient
+
+executor = ThreadPoolExecutor(max_workers=2)
+client = CosmosClient(
+    "<account-uri>",
+    "<account-key>",
+    availability_strategy_config={"threshold_ms": 150, "threshold_steps_ms": 50},
+    availability_strategy_executor=executor
+)
+```
+
+#### Customized max concurrency for hedging for async client
+
+```python
+# Customize the max concurrency on the default ThreadPoolExecutor for the sync client
+from azure.cosmos import CosmosClient
+
+client = CosmosClient(
+    "<account-uri>",
+    "<account-key>",
+    availability_strategy_config={"threshold_ms": 150, "threshold_steps_ms": 50},
+    availability_strategy_max_concurrency=2
+)
+```
+
 ## Troubleshooting
 
 ### General

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

@@ -34,7 +34,6 @@ class CrossRegionHedgingStrategyConfig:
     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)
-    - type: Must be "CrossRegionHedging" if provided
     """
     def __init__(self, config: Optional[dict[str, Any]] = None) -> None:
         if config is None:
@@ -60,9 +59,4 @@ def _validate_hedging_config(config: Optional[dict[str, Any]]) -> Optional[Cross
     if config is None:
         return None
 
-    if "type" not in config:
-        raise ValueError("Missing type field in availability strategy config")
-    if config["type"] != "CrossRegionHedging":
-        raise ValueError("Wrong availability strategy type is provided")
-
     return CrossRegionHedgingStrategyConfig(config)

sdk/cosmos/azure-cosmos/samples/examples.py

@@ -363,7 +363,7 @@
 
 # configure availability strategy config on request level
 # [START read_item_with_availability_strategy_config]
-strategy = {'type': 'CrossRegionHedging', 'threshold_ms':500, 'threshold_steps_ms':100}
+strategy = {'threshold_ms':500, 'threshold_steps_ms':100}
 container.read_item(
     item="id1",
     partition_key="pk1",

sdk/cosmos/azure-cosmos/samples/examples_async.py

@@ -367,7 +367,7 @@ async def examples_async():
 
         # configure availability strategy config on request level
         # [START read_item_with_availability_strategy_config]
-        strategy = strategy = {'type': 'CrossRegionHedging', 'threshold_ms':500, 'threshold_steps_ms':100}
+        strategy = {'threshold_ms':500, 'threshold_steps_ms':100}
         await container.read_item(
             item="id1",
             partition_key="pk1",

sdk/cosmos/azure-cosmos/tests/test_availability_strategy.py

@@ -342,14 +342,14 @@ def _clean_up_container(self, database_id: str, container_id: str):
     def test_invalid_thresholds(self, threshold_ms, threshold_steps_ms, error_message):
         """Test that creating strategy with non-positive thresholds raises ValueError when enabled"""
         with pytest.raises(ValueError, match=error_message):
-            config = {'type':'CrossRegionHedging', 'threshold_ms':threshold_ms, 'threshold_steps_ms':threshold_steps_ms}
+            config = {'threshold_ms':threshold_ms, 'threshold_steps_ms':threshold_steps_ms}
             _validate_hedging_config(config)
 
     @pytest.mark.parametrize("operation", [READ, QUERY, QUERY_PK, READ_ALL, CHANGE_FEED, CREATE, UPSERT, REPLACE, DELETE, PATCH, BATCH])
     @pytest.mark.parametrize("client_availability_strategy, request_availability_strategy", [
-        (None, {'type':'CrossRegionHedging', 'threshold_ms':150,  'threshold_steps_ms':50}),
-        ({'type':'CrossRegionHedging', 'threshold_ms':150, 'threshold_steps_ms':50}, _Unset),
-        ({'type':'CrossRegionHedging', 'threshold_ms':150, 'threshold_steps_ms':50}, {'type':'CrossRegionHedging', 'threshold_ms':150, 'threshold_steps_ms':50})
+        (None, {'threshold_ms':150,  'threshold_steps_ms':50}),
+        ({'threshold_ms':150, 'threshold_steps_ms':50}, _Unset),
+        ({'threshold_ms':150, 'threshold_steps_ms':50}, {'threshold_ms':150, 'threshold_steps_ms':50})
     ])
     def test_availability_strategy_in_steady_state(
             self,
@@ -388,9 +388,9 @@ def test_availability_strategy_in_steady_state(
 
     @pytest.mark.parametrize("operation", [READ, QUERY, QUERY_PK, READ_ALL, CHANGE_FEED, CREATE, UPSERT, REPLACE, DELETE, PATCH, BATCH])
     @pytest.mark.parametrize("client_availability_strategy, request_availability_strategy", [
-        (None, {'type':'CrossRegionHedging', 'threshold_ms':150, 'threshold_steps_ms':50}),
-        ({'type':'CrossRegionHedging', 'threshold_ms':150, 'threshold_steps_ms':50}, _Unset),
-        ({'type':'CrossRegionHedging', 'threshold_ms':700, 'threshold_steps_ms':50}, {'type':'CrossRegionHedging', 'threshold_ms':150, 'threshold_steps_ms':50})
+        (None, {'threshold_ms':150, 'threshold_steps_ms':50}),
+        ({'threshold_ms':150, 'threshold_steps_ms':50}, _Unset),
+        ({'threshold_ms':700, 'threshold_steps_ms':50}, {'threshold_ms':150, 'threshold_steps_ms':50})
     ])
     def test_client_availability_strategy_failover(
             self,
@@ -470,7 +470,7 @@ def test_non_transient_errors_from_failed_over_region(self, operation, status_co
         )
         custom_transport.add_fault(predicate_first_region, error_lambda_first_region)
 
-        strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
         setup = self._setup_method_with_custom_transport(
             custom_transport,
             multiple_write_locations=True)
@@ -520,7 +520,7 @@ def test_transient_error_from_failed_over_region(self, operation):
         )
         custom_transport.add_fault(predicate_first_region, error_lambda_first_region)
 
-        strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
         setup = self._setup_method_with_custom_transport(
             custom_transport,
             multiple_write_locations=True)
@@ -546,7 +546,7 @@ def test_transient_error_from_failed_over_region(self, operation):
     def test_request_level_disable_override_client_strategy(self, operation):
         """Test that request-level disabled policy overrides client-level enabled policy"""
         # Setup client with enabled hedging policy
-        client_strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        client_strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
 
         uri_down = _location_cache.LocationCache.GetLocationalEndpoint(self.host, self.REGION_1)
         failed_over_uri = _location_cache.LocationCache.GetLocationalEndpoint(self.host, self.REGION_2)
@@ -604,7 +604,7 @@ def test_request_level_enable_override_client_disable(self, operation):
         setup_without_fault['col'].create_item(body=doc)
 
         # Create request-level policy to enable hedging
-        request_strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        request_strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
 
         expected_uris = [uri_down, failed_over_uri]
         # Test operation with fault injection
@@ -644,7 +644,7 @@ def test_no_cross_region_request_with_exclude_regions(self, operation):
         excluded_uris = [failed_over_uri]
 
         # Test should fail with error from the first region
-        strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
         with pytest.raises(CosmosHttpResponseError) as exc_info:
             if operation in [READ, QUERY, QUERY_PK, READ_ALL, CHANGE_FEED]:
                 _perform_read_operation(
@@ -696,7 +696,7 @@ def test_no_cross_region_request_with_retry_write_disabled(self, operation):
         expected_uris = [uri_down]
         excluded_uris = [failed_over_uri]
 
-        strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
 
         # Test should fail with error from the first region
         with pytest.raises(CosmosHttpResponseError) as exc_info:
@@ -732,7 +732,7 @@ def test_per_partition_circular_breaker_with_cancelled_first_future(self, operat
 
             custom_transport = self._get_custom_transport_with_fault_injection(predicate, error_lambda)
 
-            strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+            strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
 
             setup_with_fault_injection = self._setup_method_with_custom_transport(
                 custom_transport,
@@ -815,7 +815,7 @@ def test_custom_thread_pool_executor(self):
 
         custom_transport = self._get_custom_transport_with_fault_injection(predicate, error_lambda)
 
-        strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
         setup_with_transport = self._setup_method_with_custom_transport(
             custom_transport,
             availability_strategy_executor=ThreadPoolExecutor(max_workers=1))

sdk/cosmos/azure-cosmos/tests/test_availability_strategy_async.py

@@ -359,17 +359,17 @@ async def _clean_up_container(self, client: CosmosClient, database_id:str, conta
     def test_invalid_thresholds(self, threshold_ms, threshold_steps_ms, error_message):
         """Test that creating strategy with non-positive thresholds raises ValueError when enabled"""
         with pytest.raises(ValueError, match=error_message):
-            config = {'type': 'CrossRegionHedging', 'threshold_ms': threshold_ms,
+            config = {'threshold_ms': threshold_ms,
                       'threshold_steps_ms': threshold_steps_ms}
             _validate_hedging_config(config)
 
     @pytest.mark.asyncio
     @pytest.mark.parametrize("operation", [READ, QUERY, QUERY_PK, READ_ALL, CHANGE_FEED, CREATE, UPSERT, REPLACE, DELETE, PATCH, BATCH])
     @pytest.mark.parametrize("client_availability_strategy, request_availability_strategy", [
-        (None, {'type':'CrossRegionHedging', 'threshold_ms':150, 'threshold_steps_ms':50}),
-        ({'type':'CrossRegionHedging', 'threshold_ms':150, 'threshold_steps_ms':50}, _Unset),
-        ({'type':'CrossRegionHedging', 'threshold_ms':150, 'threshold_steps_ms':50},
-         {'type':'CrossRegionHedging', 'threshold_ms':150, 'threshold_steps_ms':50})
+        (None, {'threshold_ms':150, 'threshold_steps_ms':50}),
+        ({'threshold_ms':150, 'threshold_steps_ms':50}, _Unset),
+        ({'threshold_ms':150, 'threshold_steps_ms':50},
+         {'threshold_ms':150, 'threshold_steps_ms':50})
     ])
     async def test_availability_strategy_in_steady_state(
             self,
@@ -415,9 +415,9 @@ async def test_availability_strategy_in_steady_state(
     @pytest.mark.asyncio
     @pytest.mark.parametrize("operation",[READ, QUERY, QUERY_PK, READ_ALL, CHANGE_FEED, CREATE, UPSERT, REPLACE, DELETE, PATCH, BATCH])
     @pytest.mark.parametrize("client_availability_strategy, request_availability_strategy", [
-        (None, {'type':'CrossRegionHedging', 'threshold_ms':150, 'threshold_steps_ms':50}),
-        ({'type':'CrossRegionHedging', 'threshold_ms':150, 'threshold_steps_ms':50}, _Unset),
-        ({'type':'CrossRegionHedging', 'threshold_ms':700, 'threshold_steps_ms':50}, {'type':'CrossRegionHedging', 'threshold_ms':150, 'threshold_steps_ms':50})
+        (None, {'threshold_ms':150, 'threshold_steps_ms':50}),
+        ({'threshold_ms':150, 'threshold_steps_ms':50}, _Unset),
+        ({'threshold_ms':700, 'threshold_steps_ms':50}, {'threshold_ms':150, 'threshold_steps_ms':50})
     ])
     async def test_client_availability_strategy_failover(
             self,
@@ -521,7 +521,7 @@ async def test_non_transient_errors_from_failed_over_region(self, operation, sta
         expected_uris = [uri_down, failed_over_uri]
 
         # Test should fail with original error without failover
-        strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
         with pytest.raises(CosmosHttpResponseError) as exc_info:
             if operation in [READ, QUERY, QUERY_PK, READ_ALL, CHANGE_FEED]:
                 await _perform_read_operation(
@@ -577,7 +577,7 @@ async def test_transient_error_from_failed_over_region(self, operation, setup):
         )
         custom_transport.add_fault(predicate_first_region, error_lambda_first_region)
 
-        strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
         setup_with_transport = await self._setup_method_with_custom_transport(
             setup['write_locations'],
             setup['read_locations'],
@@ -625,7 +625,7 @@ async def test_transient_error_from_failed_over_region(self, operation, setup):
     async def test_request_level_disabled_override_client_policy(self, operation, setup):
         """Test that request-level disabled policy overrides client-level enabled policy"""
         # Setup client with enabled hedging policy
-        client_strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        client_strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
 
         uri_down = _location_cache.LocationCache.GetLocationalEndpoint(self.host, setup['region_1'])
         failed_over_uri = _location_cache.LocationCache.GetLocationalEndpoint(self.host, setup['region_2'])
@@ -701,7 +701,7 @@ async def test_request_level_enabled_override_client_disabled(self, operation, s
         await setup_without_fault['col'].create_item(doc)
 
         # Create request-level enabled policy
-        request_strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        request_strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
 
         expected_uris = [uri_down, failed_over_uri]
         # Test operation with fault injection
@@ -748,7 +748,7 @@ async def test_no_cross_region_request_with_retry_write_disabled(self, operation
 
         expected_uris = [uri_down]
         excluded_uris = [failed_over_uri]
-        strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
 
         # Test should fail with error from the first region
         with pytest.raises(CosmosHttpResponseError) as exc_info:
@@ -801,7 +801,7 @@ async def test_no_cross_region_request_with_exclude_regions(self, operation, set
         expected_uris = [uri_down]
         excluded_uris = [failed_over_uri]
 
-        strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
 
         # Test should fail with error from the first region
         with pytest.raises(CosmosHttpResponseError) as exc_info:
@@ -858,7 +858,7 @@ async def test_per_partition_circular_breaker_with_cancelled_first_future(self,
 
             custom_transport = self._get_custom_transport_with_fault_injection(predicate, error_lambda)
 
-            strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+            strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
 
             setup_with_fault_injection = await self._setup_method_with_custom_transport(
                 setup['write_locations'],
@@ -949,7 +949,7 @@ async def test_max_concurrency(self, setup):
 
         custom_transport = self._get_custom_transport_with_fault_injection(predicate, error_lambda)
 
-        strategy = {'type':'CrossRegionHedging', 'threshold_ms':100, 'threshold_steps_ms':50}
+        strategy = {'threshold_ms':100, 'threshold_steps_ms':50}
         setup_with_transport = await self._setup_method_with_custom_transport(
             setup['write_locations'],
             setup['read_locations'],