[Internal] PPAF: Adds Hub Region Caching Per Partition Level

Microsoft.Azure.Cosmos/src/GatewayStoreModel.cs

@@ -101,9 +101,10 @@ await GatewayStoreModel.ApplySessionTokenAsync(
                     request.RequestContext.RegionName = regionName;
                 }
 
-                bool isPPAFEnabled = this.IsPartitionLevelFailoverEnabled();
-                // This is applicable for both per partition automatic failover and per partition circuit breaker.
-                if ((isPPAFEnabled || this.isThinClientEnabled)
+                bool isPPAFEnabled = this.IsPartitionLevelFailoverEnabled();
+                // This is applicable for both per partition automatic failover and per partition circuit breaker.
+                bool isHubRegionRoutingActive = GlobalPartitionEndpointManagerCore.IsHubRegionRoutingActive(request);
+                if ((isPPAFEnabled || this.isThinClientEnabled || isHubRegionRoutingActive)
                     && !ReplicatedResourceClient.IsMasterResource(request.ResourceType)
                     && (request.ResourceType.IsPartitioned() || request.ResourceType == ResourceType.StoredProcedure))
                 {
@@ -114,12 +115,12 @@ await GatewayStoreModel.ApplySessionTokenAsync(
                         clientCollectionCache: this.clientCollectionCache,
                         refreshCache: false);
 
-                    request.RequestContext.ResolvedPartitionKeyRange = partitionKeyRange;
+                    request.RequestContext.ResolvedPartitionKeyRange = partitionKeyRange;
 
-                    if (isPPAFEnabled)
+                    if (isPPAFEnabled || isHubRegionRoutingActive)
                     {
-                        this.globalPartitionEndpointManager.TryAddPartitionLevelLocationOverride(request);
-                    }
+                        this.globalPartitionEndpointManager.TryAddPartitionLevelLocationOverride(request, isHubRegionRoutingActive);
+                    }
                 }
 
                 bool canUseThinClient =

Microsoft.Azure.Cosmos/src/Routing/GlobalAddressResolver.cs

@@ -229,8 +229,8 @@ public async Task<PartitionAddressInformation> ResolveAsync(
         {
             IAddressResolver resolver = this.GetAddressResolver(request);
             PartitionAddressInformation partitionAddressInformation = await resolver.ResolveAsync(request, forceRefresh, cancellationToken);
-
-            if (!this.partitionKeyRangeLocationCache.TryAddPartitionLevelLocationOverride(request))
+            bool isHubRegionRoutingActive = GlobalPartitionEndpointManagerCore.IsHubRegionRoutingActive(request);
+            if (!this.partitionKeyRangeLocationCache.TryAddPartitionLevelLocationOverride(request, isHubRegionRoutingActive))
             {
                 return partitionAddressInformation;
             }

Microsoft.Azure.Cosmos/src/Routing/GlobalPartitionEndpointManager.cs

@@ -11,12 +11,18 @@ namespace Microsoft.Azure.Cosmos.Routing
 
     internal abstract class GlobalPartitionEndpointManager
     {
+        /// <summary>
+        /// A constant string representing if hub region override is present in the pk range to location cache for a request.
+        /// </summary>
+        public const string HubRegionOverridePresentInCache = "x-ms-hub-region-override-active";
+
         /// <summary>
         /// Updates the DocumentServiceRequest routing location to point
         /// new a location based if a partition level failover occurred
         /// </summary>
         public abstract bool TryAddPartitionLevelLocationOverride(
-            DocumentServiceRequest request);
+            DocumentServiceRequest request,
+            bool checkHubRegionOverrideInCache = false);
 
         /// <summary>
         /// Marks the current location unavailable for write. Future 
@@ -79,5 +85,14 @@ public abstract void SetBackgroundConnectionPeriodicRefreshTask(
         /// Returns true if circuit breaker logic for partition key ranges is active, otherwise false.
         /// </summary>
         public abstract bool IsPartitionLevelCircuitBreakerEnabled();
+
+#if !INTERNAL
+        /// <summary>
+        /// Gets a value indicating whether hub region processing is enabled for read requests
+        /// encountering repeated 404/1002 (ReadSessionNotAvailable) errors on single-master accounts.
+        /// Returns true if hub region header attachment and hub region discovery are active, otherwise false.
+        /// </summary>
+        public abstract bool IsHubRegionProcessingEnabled();
+#endif
     }
 }

Microsoft.Azure.Cosmos/src/Routing/GlobalPartitionEndpointManagerNoOp.cs

@@ -24,7 +24,8 @@ public override void SetBackgroundConnectionPeriodicRefreshTask(
         }
 
         public override bool TryAddPartitionLevelLocationOverride(
-            DocumentServiceRequest request)
+            DocumentServiceRequest request,
+            bool checkHubRegionOverrideInCache = false)
         {
             return false;
         }
@@ -70,5 +71,12 @@ public override bool IsPartitionLevelCircuitBreakerEnabled()
         {
             return false;
         }
+
+#if !INTERNAL
+        public override bool IsHubRegionProcessingEnabled()
+        {
+            return false;
+        }
+#endif
     }
 }

Microsoft.Azure.Cosmos/src/Util/ConfigurationManager.cs

@@ -78,6 +78,14 @@ internal static class ConfigurationManager
         /// </summary>
         internal static readonly string HybridSearchQueryPlanOptimizationDisabled = "AZURE_COSMOS_HYBRID_SEARCH_QUERYPLAN_OPTIMIZATION_DISABLED";
 
+        /// <summary>
+        /// A read-only string containing the environment variable name for enabling hub region processing for read requests.
+        /// When enabled (default), the SDK attaches a hub region header to read requests that encounter repeated 404/1002
+        /// (ReadSessionNotAvailable) errors, allowing the hub region to process the request directly. When disabled, the
+        /// SDK falls back to the original retry behavior without hub region header attachment.
+        /// </summary>
+        internal static readonly string HubRegionProcessingEnabled = "AZURE_COSMOS_HUB_REGION_PROCESSING_ENABLED";
+
         /// <summary>
         /// Environment variable name to enable distributed query gateway mode.
         /// </summary>
@@ -426,5 +434,22 @@ public static bool IsTcpDnsDotSuffixEnabled()
                         variable: ConfigurationManager.TcpDnsDotSuffixEnabled,
                         defaultValue: false);
         }
+
+        /// <summary>
+        /// Gets the boolean value indicating if hub region processing is enabled for read requests
+        /// encountering repeated 404/1002 (ReadSessionNotAvailable) errors on single-master accounts.
+        /// When enabled, the SDK attaches a hub region header to route read requests to the hub region
+        /// for authoritative partition resolution. When disabled, the SDK falls back to the original
+        /// retry behavior (route to write region and give up after two 404/1002 attempts).
+        /// Default: true.
+        /// </summary>
+        /// <returns>A boolean flag indicating if hub region processing is enabled.</returns>
+        public static bool IsHubRegionProcessingEnabled()
+        {
+            return ConfigurationManager
+                    .GetEnvironmentVariable(
+                        variable: ConfigurationManager.HubRegionProcessingEnabled,
+                        defaultValue: true);
+        }
     }
 }