[Cosmos] Feed Range API

[simorenoh]

This PR adds the FeedRange type and feed range APIs to azure_data_cosmos, enabling consumers to work with physical partition ranges. It uses the driver's EPK (Effective Partition Key) computation from PR #4087 for correct MultiHash (hierarchical partition key) support, including prefix partition keys.

Changes

sdk/cosmos/azure_data_cosmos/src/feed_range.rs (new)

New FeedRange type representing a contiguous [min, max) EPK range:

• FeedRange::full() — the complete EPK space
• contains() / overlaps() — containment and overlap checks
• Display / FromStr — base64-encoded JSON serialization (cross-SDK compatible)
• Serialize / Deserialize — structured JSON for embedding in documents
• Runtime validation of inclusivity flags and min ≤ max ordering
• 20 unit tests covering serialization, parsing, containment, overlap, and rejection paths

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

Two new public methods on ContainerClient:

Method	Return type	Description
read_feed_ranges(options)	Vec<FeedRange>	Returns one feed range per physical partition
feed_range_from_partition_key(pk, options)	Vec<FeedRange>	Maps a partition key to its covering feed ranges

feed_range_from_partition_key handles three cases:

Input	PK Definition	Behavior
Full key (N of N components)	Any	DriverEpk::compute() → point lookup → 1 feed range
Prefix key (< N components)	MultiHash	DriverEpk::compute_range() → overlapping lookup → 1+ feed ranges
Prefix key (< N components)	Hash (single)	Error — prefix not supported

Both methods support ReadFeedRangesOptions::with_force_refresh() to bypass the routing map cache after partition splits.

sdk/cosmos/azure_data_cosmos/src/handler/container_connection.rs

Added three accessor methods:

• partition_key_definition() — returns the PK definition from the eagerly-resolved ContainerReference
• resolve_routing_map(force_refresh) — resolves the SDK-side routing map with optional cache bypass

sdk/cosmos/azure_data_cosmos/src/hash.rs

• Added PartialOrd, Ord, Hash derives to EffectivePartitionKey (needed by FeedRange)
• Added From<String> and From<&str> impls for EffectivePartitionKey
• Made MIN_INCLUSIVE_EFFECTIVE_PARTITION_KEY / MAX_EXCLUSIVE_EFFECTIVE_PARTITION_KEY pub(crate) for reuse in feed_range.rs

sdk/cosmos/azure_data_cosmos_driver/src/models/ (visibility changes)

Made the following driver types public so the SDK can use them for EPK computation and routing:

• effective_partition_key module → pub
• partition_key_range module → pub
• EffectivePartitionKey struct → pub
• PartitionKeyRange struct → pub
• PartitionKey::values() → pub

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

Added ReadFeedRangesOptions with with_force_refresh(bool) for cache bypass control.

sdk/cosmos/azure_data_cosmos/tests/emulator_tests/cosmos_feed_ranges.rs (new)

5 emulator integration tests:

Test	What it validates
read_feed_ranges_returns_physical_partitions	Returns ≥ 2 ranges with 11000 RU/s, non-overlapping, serializable
feed_range_from_partition_key_maps_correctly	Full key → single range matching a physical partition, deterministic
feed_range_from_full_hpk_returns_single_range	Full 3-component HPK → single range within full EPK space
feed_range_from_prefix_hpk_returns_ranges	Prefix HPK (1-of-3, 2-of-3) → 1+ non-overlapping ranges
feed_range_from_partition_key_single_hash_full_key	Regression: full key on single-hash container succeeds

Architecture Note

The feed range methods use a hybrid approach:

• EPK computation → driver's EffectivePartitionKey::compute() / compute_range() (correct MultiHash support from PR #4087)
• Routing map lookup → SDK-side PartitionKeyRangeCache (via ContainerConnection::resolve_routing_map())

This is because CosmosDriver does not yet expose a resolve_routing_map() method — the driver's PartitionKeyRangeCache exists but isn't wired into the driver struct. Once that infrastructure is added (tracked separately), the feed range methods will switch to the driver's routing map, eliminating the dual-cache situation.

[Copilot]

Pull request overview

Adds a new FeedRange abstraction and accompanying ContainerClient APIs to let azure_data_cosmos consumers reason about physical partition (EPK) ranges, leveraging the driver’s EPK computation for correct MultiHash / hierarchical partition key support.

Changes:

• Introduces FeedRange with cross-SDK compatible serialization plus containment/overlap helpers.
• Adds ContainerClient::{read_feed_ranges, feed_range_from_partition_key} with optional routing map cache bypass.
• Exposes select driver model types/APIs (EPK + PK range + PK values) needed by the SDK implementation and adds emulator + unit test coverage.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
sdk/cosmos/azure_data_cosmos/tests/emulator_tests/mod.rs	Registers the new feed range emulator test module.
sdk/cosmos/azure_data_cosmos/tests/emulator_tests/cosmos_feed_ranges.rs	Adds emulator integration tests for reading feed ranges and PK→range mapping (including HPK prefix cases).
sdk/cosmos/azure_data_cosmos/src/options/mod.rs	Adds ReadFeedRangesOptions with force_refresh support.
sdk/cosmos/azure_data_cosmos/src/lib.rs	Wires in the new feed_range module and re-exports FeedRange.
sdk/cosmos/azure_data_cosmos/src/hash.rs	Extends internal EffectivePartitionKey capabilities (ordering/hash + conversions) and shares EPK boundary constants.
sdk/cosmos/azure_data_cosmos/src/handler/container_connection.rs	Adds accessors for PK definition and routing map resolution (with optional refresh).
sdk/cosmos/azure_data_cosmos/src/feed_range.rs	New FeedRange type with serialization/parsing and range relationship helpers + unit tests.
sdk/cosmos/azure_data_cosmos/src/clients/container_client.rs	Adds read_feed_ranges + feed_range_from_partition_key APIs using routing map + driver EPK computation.
sdk/cosmos/azure_data_cosmos/CHANGELOG.md	Documents the new FeedRange API surface.
sdk/cosmos/azure_data_cosmos/Cargo.toml	Adds the base64 dependency for FeedRange string serialization.
sdk/cosmos/azure_data_cosmos_driver/src/models/partition_key.rs	Makes PartitionKey::values() public for SDK-side EPK computation.
sdk/cosmos/azure_data_cosmos_driver/src/models/partition_key_range.rs	Makes PartitionKeyRange public.
sdk/cosmos/azure_data_cosmos_driver/src/models/mod.rs	Exposes effective_partition_key and partition_key_range modules publicly.
sdk/cosmos/azure_data_cosmos_driver/src/models/effective_partition_key.rs	Makes driver EffectivePartitionKey public.
sdk/cosmos/.cspell.json	Updates spellchecker allowlist for new terminology.
Cargo.lock	Locks the added base64 dependency.

[simorenoh]

/azp run rust - cosmos - weekly

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[simorenoh]

/azp run rust - cosmos - weekly

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[simorenoh]

/azp run rust - cosmos - weekly

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[github-actions]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

azure_data_cosmos_driver
azure_data_cosmos

[FabianMeiswinkel]

LGTM - Thanks

[simorenoh]

/check-enforcer override