[Cosmos] Feed Range API

sdk/cosmos/.cspell.json

@@ -53,6 +53,7 @@
     "hostnames",
     "hotfixes",
     "IMDS",
+    "inclusivity",
     "japaneast",
     "japanwest",
     "keepalive",
@@ -94,12 +95,14 @@
     "qname",
     "readfeed",
     "reqs",
+    "Replicaset",
     "Retriable",
     "retryable",
     "rfind",
     "RNTBD",
     "roundtrips",
     "rwcache",
+    "sess",
     "southafricanorth",
     "southafricawest",
     "southcentralus",
@@ -124,6 +127,7 @@
     "uknorth",
     "uksouth",
     "ukwest",
+    "unsharded",
     "upsert",
     "upserted",
     "upserting",
@@ -153,6 +157,10 @@
     "westus",
     "yxxx"
   ],
+  "ignorePaths": [
+    "live-platform-matrix.json",
+    "release-platform-matrix.json"
+  ],
   "overrides": [
     {
       "filename": [

sdk/cosmos/AGENTS.md

@@ -384,6 +384,36 @@ let driver = Driver::builder()
 - Use `assert!` for boolean assertions instead of `assert_eq!(value, true/false)`
 - **Prefer the strongest assertion that matches the contract**: Use `assert_eq!(vec, expected_vec)` instead of `assert!(vec.contains(x))` — the former catches both missing and extra elements. In general, assert exact values over partial properties.
 
+### No Round-Trip Tests
+
+**Parse and format/display tests must be one-directional**, never round-trip.
+
+Round-tripping (parse → format → parse → assert equality) hides symmetric bugs: if both
+parse and format interpret a value wrong in the same way, the test still passes.
+
+Every test must be exactly one of:
+
+1. **Parse test** — hardcoded string input → `assert_eq!` against a directly-constructed expected structure.
+2. **Format test** — directly-constructed structure → `assert_eq!` against a hardcoded expected string.
+
+```rust
+// ❌ BAD: round-trip — symmetric bugs are invisible
+let t = "some_input".parse::<MyType>().unwrap();
+let s = t.to_string();
+let t2 = s.parse::<MyType>().unwrap();
+assert_eq!(t, t2);
+
+// ✅ GOOD: parse test — string in, assert structure
+let t = "some_input".parse::<MyType>().unwrap();
+assert_eq!(t.field, expected_value);
+
+// ✅ GOOD: format test — structure in, assert string
+let t = MyType { field: value };
+assert_eq!(t.to_string(), "expected_output");
+```
+
+This also applies to `serde_json::to_string` / `serde_json::from_str` pairs and any other serialize/deserialize combinations.
+
 ## Code Quality and Validation
 
 ### Automatic Formatting (CRITICAL)

sdk/cosmos/azure_data_cosmos/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Release History
 
+## 0.33.0 (Unreleased)
+
+### Features Added
+- Added `FeedRange` type with `ContainerClient::read_feed_ranges()` and `ContainerClient::feed_range_from_partition_key()`. ([#3987](https://github.com/Azure/azure-sdk-for-rust/pull/3987))
+
+### Breaking Changes
+
+### Bugs Fixed
+
+### Other Changes
+
 ## 0.32.0 (2026-04-09)
 
 ### Features Added
@@ -27,6 +38,7 @@
 ### Other Changes
 
 - `ContainerClient::read_item` now executes through the `azure_data_cosmos_driver` pipeline, gaining driver-level transport, routing, and retry capabilities. ([#4053](https://github.com/Azure/azure-sdk-for-rust/pull/4053))
+- `ContainerClient::create_item` now executes through the `azure_data_cosmos_driver` pipeline, gaining driver-level transport, routing, and retry capabilities. ([#4111](https://github.com/Azure/azure-sdk-for-rust/pull/4111))
 - Removed internal OpenTelemetry tracing spans pending alignment with [Cosmos DB semantic conventions](https://opentelemetry.io/docs/specs/semconv/registry/attributes/azure/#azure-cosmos-db-attributes). Spans will return in a future release. ([#4104](https://github.com/Azure/azure-sdk-for-rust/pull/4104))
 - Added `azure_data_cosmos_driver` as a runtime dependency for internal transport and caching. ([#4005](https://github.com/Azure/azure-sdk-for-rust/pull/4005))
 

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

@@ -3,11 +3,12 @@
 
 use crate::{
     clients::OffersClient,
+    feed_range::FeedRange,
     models::{
         BatchResponse, ContainerProperties, CosmosResponse, ItemResponse, ResourceResponse,
         ThroughputProperties,
     },
-    options::{BatchOptions, QueryOptions, ReadContainerOptions},
+    options::{BatchOptions, QueryOptions, ReadContainerOptions, ReadFeedRangesOptions},
     pipeline::GatewayPipeline,
     resource_context::{ResourceLink, ResourceType},
     transactional_batch::TransactionalBatch,
@@ -24,7 +25,10 @@ use crate::routing::global_partition_endpoint_manager::GlobalPartitionEndpointMa
 use crate::routing::partition_key_range_cache::PartitionKeyRangeCache;
 use azure_core::http::headers::AsHeaders;
 use azure_core::http::Context;
-use azure_data_cosmos_driver::models::{ContainerReference, CosmosOperation, ItemReference};
+use azure_data_cosmos_driver::models::{
+    effective_partition_key::EffectivePartitionKey as DriverEpk, ContainerReference,
+    CosmosOperation, ItemReference, PartitionKeyKind,
+};
 use azure_data_cosmos_driver::CosmosDriver;
 use serde::{de::DeserializeOwned, Serialize};
 
@@ -37,7 +41,6 @@ pub struct ContainerClient {
     items_link: ResourceLink,
     pipeline: Arc<GatewayPipeline>,
     container_connection: Arc<ContainerConnection>,
-    #[expect(dead_code, reason = "will be used when tracing spans are re-added")]
     container_id: String,
     driver: Arc<CosmosDriver>,
     container_ref: ContainerReference,
@@ -778,6 +781,194 @@ impl ContainerClient {
             .await
             .map(BatchResponse::new)
     }
+
+    /// Gets the feed ranges for this container.
+    ///
+    /// Each [`FeedRange`] represents a contiguous range of the container's partition key space,
+    /// corresponding to one physical partition.
+    ///
+    /// # Arguments
+    ///
+    /// * `options` - Optional [`ReadFeedRangesOptions`] to control cache behavior.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// # async fn doc() -> Result<(), Box<dyn std::error::Error>> {
+    /// # let container_client: azure_data_cosmos::clients::ContainerClient = panic!("this is a non-running example");
+    /// let ranges = container_client.read_feed_ranges(None).await?;
+    /// println!("Container has {} physical partitions", ranges.len());
+    /// # Ok(())
+    /// # }
+    /// ```
+    #[tracing::instrument(skip_all, fields(id = self.container_id))]
+    pub async fn read_feed_ranges(
+        &self,
+        options: Option<ReadFeedRangesOptions>,
+    ) -> azure_core::Result<Vec<FeedRange>> {
+        let options = options.unwrap_or_default();
+
+        let routing_map = self
+            .container_connection
+            .resolve_routing_map(options.force_refresh())
+            .await?
+            .ok_or_else(|| {
+                azure_core::Error::with_message(
+                    azure_core::error::ErrorKind::Other,
+                    "failed to resolve routing map for container",
+                )
+            })?;
+
+        let feed_ranges = routing_map
+            .ordered_partition_key_ranges()
+            .iter()
+            .map(FeedRange::from_sdk_partition_key_range)
+            .collect();
+
+        Ok(feed_ranges)
+    }
+
+    /// Returns the [`FeedRange`]s of the physical partitions covering the given partition key.
+    ///
+    /// For full partition keys (all components provided), this returns a single-element
+    /// `Vec` containing the feed range of the physical partition that owns the key.
+    ///
+    /// For prefix partition keys on MultiHash (hierarchical) containers, this returns
+    /// one or more feed ranges covering all physical partitions that overlap the prefix's
+    /// effective partition key range.
+    ///
+    /// # Arguments
+    ///
+    /// * `partition_key` - The partition key value (full or prefix for HPK containers).
+    /// * `options` - Optional [`ReadFeedRangesOptions`] to control cache behavior.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if:
+    /// - The partition key has no components (empty).
+    /// - The partition key has more components than the container's partition key definition.
+    /// - A prefix key is provided for a non-MultiHash (single-hash) container.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// # async fn doc() -> Result<(), Box<dyn std::error::Error>> {
+    /// # let container_client: azure_data_cosmos::clients::ContainerClient = panic!("this is a non-running example");
+    /// // Full key — returns one feed range:
+    /// let ranges = container_client
+    ///     .feed_range_from_partition_key("my_partition_key", None)
+    ///     .await?;
+    /// assert_eq!(ranges.len(), 1);
+    /// # Ok(())
+    /// # }
+    /// ```
+    #[tracing::instrument(skip_all, fields(id = self.container_id))]
+    pub async fn feed_range_from_partition_key(
+        &self,
+        partition_key: impl Into<PartitionKey>,
+        options: Option<ReadFeedRangesOptions>,
+    ) -> azure_core::Result<Vec<FeedRange>> {
+        let partition_key = partition_key.into();
+        let driver_pk = partition_key.into_driver_partition_key();
+        let options = options.unwrap_or_default();
+        let pk_def = self.container_connection.partition_key_definition();
+        let values = driver_pk.values();
+
+        // Validate inputs.
+        if values.is_empty() {
+            return Err(azure_core::Error::with_message(
+                azure_core::error::ErrorKind::Other,
+                "partition key must have at least one component",
+            ));
+        }
+        if values.len() > pk_def.paths().len() {
+            return Err(azure_core::Error::with_message(
+                azure_core::error::ErrorKind::Other,
+                format!(
+                    "partition key has {} components but container definition has {} paths",
+                    values.len(),
+                    pk_def.paths().len()
+                ),
+            ));
+        }
+
+        let is_prefix =
+            pk_def.kind() == PartitionKeyKind::MultiHash && values.len() < pk_def.paths().len();
+
+        if !is_prefix && values.len() != pk_def.paths().len() {
+            return Err(azure_core::Error::with_message(
+                azure_core::error::ErrorKind::Other,
+                "prefix partition keys are only supported for MultiHash (hierarchical) containers",
+            ));
+        }
+
+        let routing_map = self
+            .container_connection
+            .resolve_routing_map(options.force_refresh())
+            .await?
+            .ok_or_else(|| {
+                azure_core::Error::with_message(
+                    azure_core::error::ErrorKind::Other,
+                    "failed to resolve routing map for container",
+                )
+            })?;
+
+        if is_prefix {
+            // Prefix key — compute EPK range, find all overlapping partitions.
+            let epk_range = DriverEpk::compute_range(values, pk_def)?;
+            let query_range = crate::routing::range::Range::new(
+                epk_range.start.as_str().to_owned(),
+                epk_range.end.as_str().to_owned(),
+                true,
+                false,
+            );
+            let pkranges = routing_map.get_overlapping_ranges(&query_range);
+            if pkranges.is_empty() {
+                // Routing map may be stale (e.g. after a partition split). Refresh and retry once.
+                let refreshed = self
+                    .container_connection
+                    .resolve_routing_map(true)
+                    .await?
+                    .ok_or_else(|| {
+                        azure_core::Error::with_message(
+                            azure_core::error::ErrorKind::Other,
+                            "failed to resolve routing map for container after refresh",
+                        )
+                    })?;
+                Ok(refreshed
+                    .get_overlapping_ranges(&query_range)
+                    .iter()
+                    .map(FeedRange::from_sdk_partition_key_range)
+                    .collect())
+            } else {
+                Ok(pkranges
+                    .iter()
+                    .map(FeedRange::from_sdk_partition_key_range)
+                    .collect())
+            }
+        } else {
+            // Full key — compute single EPK, point lookup for one partition.
+            let epk = DriverEpk::compute(values, pk_def.kind(), pk_def.version());
+            match routing_map.get_range_by_effective_partition_key(epk.as_str()) {
+                Ok(pkr) => Ok(vec![FeedRange::from_sdk_partition_key_range(pkr)]),
+                Err(_) => {
+                    // Routing map may be stale. Refresh and retry once.
+                    let refreshed = self
+                        .container_connection
+                        .resolve_routing_map(true)
+                        .await?
+                        .ok_or_else(|| {
+                            azure_core::Error::with_message(
+                                azure_core::error::ErrorKind::Other,
+                                "failed to resolve routing map for container after refresh",
+                            )
+                        })?;
+                    let pkr = refreshed.get_range_by_effective_partition_key(epk.as_str())?;
+                    Ok(vec![FeedRange::from_sdk_partition_key_range(pkr)])
+                }
+            }
+        }
+    }
 }
 
 #[cfg(test)]
@@ -809,5 +1000,9 @@ mod tests {
 
         // Batch operations
         assert_send(client.execute_transactional_batch(todo!(), todo!()));
+
+        // Feed range operations
+        assert_send(client.read_feed_ranges(todo!()));
+        assert_send(client.feed_range_from_partition_key("", todo!()));
     }
 }