cosmos: Add RoutingStrategy::PreferredRegions (#4485)

This adds the `PreferredRegions` routing strategy, which just accepts a
flat list of regions and prioritizes read/write regions using that list.
This is the same logic used by other SDKs when "Preferred Regions" is
set.

Author: analogrelay

sdk/cosmos/azure_data_cosmos/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Features Added
 
+- Added `RegionStrategy::PreferredRegions` to allow specifying a fixed region preference order for failover, hedging, and retry. ([#4485](https://github.com/Azure/azure-sdk-for-rust/pull/4485))
 - Standardized every client-method options type with a public `operation: OperationOptions` field and `with_operation_options(OperationOptions) -> Self` setter, so any per-request `OperationOptions` setting can be configured via any options type. The following options types previously had no way to attach `OperationOptions` and now do: `ReadContainerOptions`, `ReadDatabaseOptions`, `ReplaceContainerOptions`, `CreateContainerOptions`, `CreateDatabaseOptions`, `DeleteContainerOptions`, `DeleteDatabaseOptions`, `QueryContainersOptions`, `QueryDatabasesOptions`, `ThroughputOptions`, `ReadFeedRangesOptions`. For `CreateContainerOptions` / `CreateDatabaseOptions` / `ReplaceContainerOptions`, the SDK still forces `content_response_on_write = Enabled` on the resolved options because control-plane mutations require the response body. `ReadFeedRangesOptions::operation` is currently inert (the underlying routing-map cache does not go through the operation pipeline) but is added for shape consistency with the other options types.
 - Added `new()` constructors and `with_x` consuming setters to multi-required-field model types so callers can build them declaratively without struct-literal syntax (which is now blocked by `#[non_exhaustive]`): `VectorEmbedding::new(path, data_type, dimensions, distance_function)` + `with_path` / `with_data_type` / `with_dimensions` / `with_distance_function`; `ConflictResolutionPolicy::new(mode)` + `with_resolution_path` / `with_resolution_procedure`; `SpatialIndex::new(path)` + `with_type` (singular pusher onto `types`); `CompositeIndexProperty::new(path, order)` + `with_path` / `with_order`; `VectorIndex::new(path, index_type)` + `with_path` / `with_index_type`. These types do **not** implement `Default` — their constructors require values that have no meaningful default.
 - Derived `Default` on `VectorEmbeddingPolicy`, `UniqueKeyPolicy`, `UniqueKey`, `PropertyPath`, and `CompositeIndex`, and added singular `with_x` pushers / setters: `VectorEmbeddingPolicy::with_embedding`, `UniqueKeyPolicy::with_unique_key`, `UniqueKey::with_path`, `PropertyPath::with_path`, and `CompositeIndex::with_property`. This matches the existing `IndexingPolicy::with_included_path` style and lets callers build these policies declaratively without constructing intermediate `Vec`s.

sdk/cosmos/azure_data_cosmos/src/clients/cosmos_client.rs

@@ -87,6 +87,7 @@ impl CosmosClient {
     pub fn builder() -> CosmosClientBuilder {
         CosmosClientBuilder::new()
     }
+
     /// Gets a [`DatabaseClient`] that can be used to access the database with the specified ID.
     ///
     /// # Arguments

sdk/cosmos/azure_data_cosmos/src/clients/cosmos_client_builder.rs

@@ -277,17 +277,10 @@ impl CosmosClientBuilder {
     ///
     /// Returns an error if the client cannot be constructed.
     pub async fn build(
-        mut self,
+        self,
         account: AccountReference,
         routing_strategy: RoutingStrategy,
     ) -> azure_core::Result<CosmosClient> {
-        // Apply the region selection strategy to internal options.
-        match routing_strategy {
-            RoutingStrategy::ProximityTo(region) => {
-                self.options.application_region = Some(region);
-            }
-        }
-
         let (account_endpoint, credential) = account.into_parts();
         let endpoint = account_endpoint.into_url();
 
@@ -302,20 +295,6 @@ impl CosmosClientBuilder {
             std::sync::Arc<azure_data_cosmos_driver::fault_injection::FaultInjectionRule>,
         > = self.fault_injection_rules;
 
-        let preferred_regions = if let Some(ref region) = self.options.application_region {
-            crate::region_proximity::generate_preferred_region_list(region)
-                .map(|s| s.to_vec())
-                .unwrap_or_else(|| {
-                    tracing::warn!(
-                        region = %region,
-                        "unrecognized application region; falling back to account-defined region order"
-                    );
-                    Vec::new()
-                })
-        } else {
-            Vec::new()
-        };
-
         // Preserve the SDK's historical default: per-partition circuit breaker
         // (PPCB) is enabled unless the user explicitly opts out via
         // `AZURE_COSMOS_PER_PARTITION_CIRCUIT_BREAKER_ENABLED=false`. The
@@ -394,10 +373,7 @@ impl CosmosClientBuilder {
                 })?;
         }
         let driver_runtime = driver_runtime_builder.build().await?;
-        let driver_options =
-            azure_data_cosmos_driver::options::DriverOptions::builder(driver_account)
-                .with_preferred_regions(preferred_regions)
-                .build();
+        let driver_options = build_driver_options(driver_account, routing_strategy);
         let driver = driver_runtime
             .get_or_create_driver(driver_options.account().clone(), Some(driver_options))
             .await?;
@@ -408,6 +384,38 @@ impl CosmosClientBuilder {
     }
 }
 
+/// Builds [`DriverOptions`](azure_data_cosmos_driver::options::DriverOptions) for the given
+/// account and routing strategy.
+///
+/// The routing strategy is converted to an ordered preferred-regions list:
+///
+/// - [`RoutingStrategy::ProximityTo`] expands to a proximity-sorted list of all
+///   Azure regions, with the specified region first. An unrecognized region logs
+///   a warning and falls back to an empty list, which causes the driver to use
+///   the account's own region order.
+/// - [`RoutingStrategy::PreferredRegions`] passes the caller's list through unchanged.
+fn build_driver_options(
+    account: azure_data_cosmos_driver::models::AccountReference,
+    strategy: RoutingStrategy,
+) -> azure_data_cosmos_driver::options::DriverOptions {
+    let preferred_regions = match strategy {
+        RoutingStrategy::ProximityTo(region) =>
+            crate::region_proximity::generate_preferred_region_list(&region)
+                .map(|s| s.to_vec())
+                .unwrap_or_else(|| {
+                    tracing::warn!(
+                        region = %region,
+                        "unrecognized application region; falling back to account-defined region order"
+                    );
+                    Vec::new()
+                }),
+        RoutingStrategy::PreferredRegions(regions) => regions,
+    };
+    azure_data_cosmos_driver::options::DriverOptions::builder(account)
+        .with_preferred_regions(preferred_regions)
+        .build()
+}
+
 /// Builds a driver [`AccountReference`](azure_data_cosmos_driver::models::AccountReference)
 /// from the SDK's credential and endpoint.
 fn build_driver_account(
@@ -427,15 +435,10 @@ fn build_driver_account(
     base.with_backup_endpoints(backup_endpoints)
 }
 
-// Unit tests for routing-strategy behavior were removed because
-// CosmosClient::builder().build() now eagerly creates a CosmosDriver,
-// which requires a real endpoint. Re-add once fault injection is linked
-// from the SDK to the driver.
-
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::UserAgentSuffix;
+    use crate::{Region, UserAgentSuffix};
 
     /// Reproduces the bug where `CosmosClientBuilder::with_user_agent_suffix`
     /// did not forward the suffix to the driver runtime, causing the
@@ -550,4 +553,52 @@ mod tests {
             "explicit env-var opt-out must propagate to the driver runtime"
         );
     }
+
+    fn test_account() -> azure_data_cosmos_driver::models::AccountReference {
+        azure_data_cosmos_driver::models::AccountReference::with_master_key(
+            "https://test.documents.azure.com/".parse().unwrap(),
+            "dGVzdA==",
+        )
+    }
+
+    /// `ProximityTo` a known region produces a non-empty preferred_regions list
+    /// with the source region first.
+    #[test]
+    fn proximity_to_known_region_starts_with_source() {
+        let opts = build_driver_options(
+            test_account(),
+            RoutingStrategy::ProximityTo(Region::EAST_US),
+        );
+        let regions = opts.preferred_regions();
+        assert!(
+            !regions.is_empty(),
+            "should produce a non-empty list for a known region"
+        );
+        assert_eq!(regions[0], Region::EAST_US, "source region should be first");
+    }
+
+    /// `ProximityTo` an unrecognized region falls back to an empty preferred_regions
+    /// list so the driver uses the account's own region order.
+    #[test]
+    fn proximity_to_unknown_region_returns_empty_list() {
+        let opts = build_driver_options(
+            test_account(),
+            RoutingStrategy::ProximityTo(Region::from("not-a-real-region")),
+        );
+        assert!(
+            opts.preferred_regions().is_empty(),
+            "unrecognized region should yield an empty list"
+        );
+    }
+
+    /// `PreferredRegions` passes the caller's list through to the driver options unchanged.
+    #[test]
+    fn preferred_regions_passes_through_unchanged() {
+        let input = vec![Region::WEST_US, Region::EAST_US, Region::WEST_EUROPE];
+        let opts = build_driver_options(
+            test_account(),
+            RoutingStrategy::PreferredRegions(input.clone()),
+        );
+        assert_eq!(opts.preferred_regions(), input.as_slice());
+    }
 }

sdk/cosmos/azure_data_cosmos/src/options/mod.rs

@@ -30,7 +30,6 @@ pub struct CosmosClientOptions {
     /// unless overridden by per-request options.
     pub(crate) operation: OperationOptions,
     pub(crate) user_agent_suffix: Option<UserAgentSuffix>,
-    pub(crate) application_region: Option<Region>,
 }
 
 impl CosmosClientOptions {

sdk/cosmos/azure_data_cosmos/src/routing_strategy.rs

@@ -33,4 +33,14 @@ pub enum RoutingStrategy {
     /// Specifying an unknown region name results in undefined region
     /// selection behavior that may change in future versions of the SDK.
     ProximityTo(Region),
+
+    /// Select target regions using a fixed preference order.
+    ///
+    /// This list **does not** restrict which regions the SDK may select for routing,
+    /// only the order in which it considers them. After failover exhausts the list of preferred regions,
+    /// the SDK will arbitrarily select from other available regions.
+    ///
+    /// If you need to prohibit the SDK from selecting certain regions,
+    /// use [`OperationOptions::excluded_regions`](crate::options::OperationOptions::excluded_regions).
+    PreferredRegions(Vec<Region>),
 }