Cherry-pick: Fix pk_range_cache to use .item_by_rid() for correct URL fetching (#4041)

Cherry-pick of #4032 into `release/azure_data_cosmos-previews`.

Fixes pk_range_cache to use `.item_by_rid()` for correct URL fetching,
ensuring partition key range lookups use the correct container resource
ID.

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

Author: tvaron3

sdk/cosmos/.cspell.json

@@ -73,6 +73,7 @@
         "Kusto",
         "libazurecosmos",
         "linearizability",
+        "LLZA",
         "makefiles",
         "MEMORYSTATUSEX",
         "moka",
@@ -105,6 +106,7 @@
         "perfdb",
         "perfresults",
         "PIDS",
+        "Pigw",
         "Pkrange",
         "PKRANGE",
         "pkranges",

sdk/cosmos/azure_data_cosmos/src/routing/partition_key_range_cache.rs

@@ -144,6 +144,13 @@ impl PartitionKeyRangeCache {
             )
             .await;
 
+        if let Err(ref e) = routing_map {
+            tracing::warn!(
+                collection_rid,
+                error = %e,
+                "Failed to fetch routing map for collection"
+            );
+        }
         Ok(routing_map.ok())
     }
 
@@ -189,7 +196,7 @@ impl PartitionKeyRangeCache {
             let pk_range_link = self
                 .database_link
                 .feed(ResourceType::Containers)
-                .item(collection_rid)
+                .item_by_rid(collection_rid)
                 .feed(ResourceType::PartitionKeyRanges);
             let response = self
                 .execute_partition_key_range_read_change_feed(
@@ -673,4 +680,61 @@ mod tests {
         assert!(range.target_throughput.is_some());
         assert_eq!(range.target_throughput.unwrap(), 1000.0);
     }
+
+    // Tests verifying that the pkranges resource link uses item_by_rid() so that
+    // collection RIDs (which are base64-encoded and can contain '=', '+', '/') are
+    // not URL-percent-encoded. Using item() would encode '=' to '%3D', causing 404s.
+
+    #[test]
+    fn pkranges_link_rid_with_equals_is_not_encoded() {
+        // RIDs like "pLLZAIuPigw=" contain '=' which item() would encode to '%3D'.
+        // item_by_rid() must preserve it as-is.
+        let collection_rid = "pLLZAIuPigw=";
+        let database_link = ResourceLink::root(ResourceType::Databases).item("perfdb");
+        let pk_range_link = database_link
+            .feed(ResourceType::Containers)
+            .item_by_rid(collection_rid)
+            .feed(ResourceType::PartitionKeyRanges);
+
+        // Correct: '=' preserved, not encoded to '%3D'
+        assert_eq!(
+            "dbs/perfdb/colls/pLLZAIuPigw=/pkranges",
+            pk_range_link.path()
+        );
+    }
+
+    #[test]
+    fn pkranges_link_item_encodes_equals_incorrectly() {
+        // Demonstrates the bug: item() URL-encodes '=' to '%3D', producing a path
+        // that Cosmos DB cannot find (404).
+        let collection_rid = "pLLZAIuPigw=";
+        let database_link = ResourceLink::root(ResourceType::Databases).item("perfdb");
+        let pk_range_link_wrong = database_link
+            .feed(ResourceType::Containers)
+            .item(collection_rid)
+            .feed(ResourceType::PartitionKeyRanges);
+
+        // Wrong: '=' is encoded to '%3D', causing 404 from Cosmos DB
+        assert!(
+            pk_range_link_wrong.path().contains("%3D"),
+            "item() should URL-encode '=' to '%3D'"
+        );
+        assert_eq!(
+            "dbs/perfdb/colls/pLLZAIuPigw%3D/pkranges",
+            pk_range_link_wrong.path()
+        );
+    }
+
+    #[test]
+    fn pkranges_link_rid_with_plus_is_not_encoded() {
+        // RIDs may also contain '+' (base64 char). item_by_rid() must preserve it.
+        let collection_rid = "AB+CD/EF==";
+        let database_link = ResourceLink::root(ResourceType::Databases).item("mydb");
+        let pk_range_link = database_link
+            .feed(ResourceType::Containers)
+            .item_by_rid(collection_rid)
+            .feed(ResourceType::PartitionKeyRanges);
+
+        assert_eq!("dbs/mydb/colls/AB+CD/EF==/pkranges", pk_range_link.path());
+    }
 }