Azure · jeet1995 · Apr 16, 2026 · Apr 16, 2026 · Apr 16, 2026 · Apr 16, 2026
@@ -4,6 +4,7 @@
 
 #### Features Added
 * Added support for change feed with `startFrom` point-in-time on merged partitions by enabling the `CHANGE_FEED_WITH_START_TIME_POST_MERGE` SDK capability. - See [PR 48752](https://github.com/Azure/azure-sdk-for-java/pull/48752)
+* Enabled `ReadConsistencyStrategy` for Gateway V1 (compute gateway) and Gateway V2 (thin client proxy). Previously only supported in Direct mode. Also added client-side validation for `GLOBAL_STRONG` on non-Strong consistency accounts. - See [PR 48787](https://github.com/Azure/azure-sdk-for-java/pull/48787)
 * Added new `readManyByPartitionKeys` API on `CosmosAsyncContainer` / `CosmosContainer` to bulk-query all documents matching a list of partition key values with better efficiency than issuing individual queries. See [PR 48801](https://github.com/Azure/azure-sdk-for-java/pull/48801)
 * Added `CosmosReadManyByPartitionKeysRequestOptions` - a dedicated request-options type for `readManyByPartitionKeys` that exposes `setContinuationToken(String)` for resuming previous invocations and `setMaxConcurrentBatchPrefetch(int)` to bound per-call prefetch parallelism. See [PR 48801](https://github.com/Azure/azure-sdk-for-java/pull/48801)
 * Added `CosmosReadManyByPartitionKeysRequestOptions.setMaxBatchSize(Integer)` to set the max. number of partition keys used for a single batch. See [PR 48930](https://github.com/Azure/azure-sdk-for-java/pull/48930)

@@ -146,20 +146,26 @@ private RxDocumentServiceRequest createDocumentServiceRequest() {
 
         if (this.options.getReadConsistencyStrategy() != null) {
 
-            String readConsistencyStrategyName = options.getReadConsistencyStrategy().toString();
-            this.client.validateAndLogNonDefaultReadConsistencyStrategy(readConsistencyStrategyName);
-            headers.put(HttpConstants.HttpHeaders.READ_CONSISTENCY_STRATEGY, readConsistencyStrategyName);
+            this.client.validateReadConsistencyStrategy(options.getReadConsistencyStrategy());
+
+            if (this.options.getReadConsistencyStrategy() != ReadConsistencyStrategy.DEFAULT) {
+                headers.put(
+                    HttpConstants.HttpHeaders.READ_CONSISTENCY_STRATEGY,
+                    options.getReadConsistencyStrategy().toString());
+            }
 
             consistencyLevelOverrideApplicable =
                 this.options.getReadConsistencyStrategy() == ReadConsistencyStrategy.DEFAULT;
         }
 
         if (consistencyLevelOverrideApplicable && this.client.getReadConsistencyStrategy() != null) {
-            String readConsistencyStrategyName = this.client.getReadConsistencyStrategy().toString();
-            this.client.validateAndLogNonDefaultReadConsistencyStrategy(readConsistencyStrategyName);
-            headers.put(
-                HttpConstants.HttpHeaders.READ_CONSISTENCY_STRATEGY,
-                readConsistencyStrategyName);
+            this.client.validateReadConsistencyStrategy(this.client.getReadConsistencyStrategy());
+
+            if (this.client.getReadConsistencyStrategy() != ReadConsistencyStrategy.DEFAULT) {
+                headers.put(
+                    HttpConstants.HttpHeaders.READ_CONSISTENCY_STRATEGY,
+                    this.client.getReadConsistencyStrategy().toString());
+            }
 
             consistencyLevelOverrideApplicable =
                 this.client.getReadConsistencyStrategy() == ReadConsistencyStrategy.DEFAULT;

@@ -1927,16 +1927,18 @@ private static void validateResource(Resource resource) {
         }
     }
 
-    public void validateAndLogNonDefaultReadConsistencyStrategy(String readConsistencyStrategyName) {
-        if (this.connectionPolicy.getConnectionMode() != ConnectionMode.DIRECT
-            && readConsistencyStrategyName != null
-            && ! readConsistencyStrategyName.equalsIgnoreCase(ReadConsistencyStrategy.DEFAULT.toString())) {
-
-            logger.warn(
-                "ReadConsistencyStrategy {} defined in Gateway mode. "
-                    + "This version of the SDK only supports ReadConsistencyStrategy in DIRECT mode. "
-                    + "This setting will be ignored.",
-                readConsistencyStrategyName);
+    public void validateReadConsistencyStrategy(ReadConsistencyStrategy readConsistencyStrategy) {
+        if (readConsistencyStrategy == ReadConsistencyStrategy.GLOBAL_STRONG) {
+            ConsistencyLevel accountConsistency = this.getDefaultConsistencyLevelOfAccount();
+            if (accountConsistency != ConsistencyLevel.STRONG) {
+                throw new BadRequestException(
+                    String.format(
+                        RMResources.ReadConsistencyStrategyGlobalStrongOnlyAllowedForGlobalStrongAccount,
+                        readConsistencyStrategy.toString(),
+                        HttpConstants.HttpHeaders.READ_CONSISTENCY_STRATEGY,
+                        ConsistencyLevel.STRONG,
+                        accountConsistency));
+            }
         }
     }
 
@@ -1963,8 +1965,12 @@ private Map<String, String> getRequestHeaders(RequestOptions options, ResourceTy
             && operationType.isReadOnlyOperation()) {
 
             String readConsistencyStrategyName = readConsistencyStrategy.toString();
-            this.validateAndLogNonDefaultReadConsistencyStrategy(readConsistencyStrategyName);
+            this.validateReadConsistencyStrategy(readConsistencyStrategy);
             headers.put(HttpConstants.HttpHeaders.READ_CONSISTENCY_STRATEGY, readConsistencyStrategyName);
+            // Compute gateway rejects requests with both x-ms-consistency-level and
+            // x-ms-cosmos-read-consistency-strategy headers. When readConsistencyStrategy is set, remove
+            // consistency-level — readConsistencyStrategy takes precedence.
+            headers.remove(HttpConstants.HttpHeaders.CONSISTENCY_LEVEL);
         }
 
         if (options == null) {
@@ -2008,13 +2014,20 @@ private Map<String, String> getRequestHeaders(RequestOptions options, ResourceTy
             && operationType.isReadOnlyOperation()) {
 
             String readConsistencyStrategyName = options.getReadConsistencyStrategy().toString();
-            this.validateAndLogNonDefaultReadConsistencyStrategy(readConsistencyStrategyName);
+            this.validateReadConsistencyStrategy(options.getReadConsistencyStrategy());
             headers.put(
                 HttpConstants.HttpHeaders.READ_CONSISTENCY_STRATEGY,
                 readConsistencyStrategyName);
+            // Compute gateway rejects requests with both x-ms-consistency-level and
+            // x-ms-cosmos-read-consistency-strategy headers. When readConsistencyStrategy is set, remove
+            // consistency-level — readConsistencyStrategy takes precedence.
+            headers.remove(HttpConstants.HttpHeaders.CONSISTENCY_LEVEL);
         }
 
-        if (options.getConsistencyLevel() != null) {
+        if (options.getConsistencyLevel() != null
+            && !headers.containsKey(HttpConstants.HttpHeaders.READ_CONSISTENCY_STRATEGY)) {
+            // Only set ConsistencyLevel when ReadConsistencyStrategy is NOT already present.
+            // readConsistencyStrategy takes precedence — setting both causes gateway rejection.
             headers.put(HttpConstants.HttpHeaders.CONSISTENCY_LEVEL, options.getConsistencyLevel().toString());
         }
 
@@ -5432,8 +5445,8 @@ public ConsistencyLevel getConsistencyLevel() {
             }
 
             @Override
-            public void validateAndLogNonDefaultReadConsistencyStrategy(String readConsistencyStrategyName) {
-                RxDocumentClientImpl.this.validateAndLogNonDefaultReadConsistencyStrategy(readConsistencyStrategyName);
+            public void validateReadConsistencyStrategy(ReadConsistencyStrategy readConsistencyStrategy) {
+                RxDocumentClientImpl.this.validateReadConsistencyStrategy(readConsistencyStrategy);
             }
 
             @Override

@@ -12,7 +12,6 @@
 import com.azure.cosmos.implementation.caches.RxPartitionKeyRangeCache;
 import com.azure.cosmos.implementation.directconnectivity.GatewayServiceConfigurationReader;
 import com.azure.cosmos.implementation.directconnectivity.HttpUtils;
-import com.azure.cosmos.implementation.directconnectivity.RequestHelper;
 import com.azure.cosmos.implementation.directconnectivity.StoreResponse;
 import com.azure.cosmos.implementation.directconnectivity.Uri;
 import com.azure.cosmos.implementation.directconnectivity.WebExceptionUtility;
@@ -320,9 +319,77 @@ public Mono<RxDocumentServiceResponse> performRequestInternal(RxDocumentServiceR
             });
     }
 
+    /**
+     * Resolves contention between ConsistencyLevel and ReadConsistencyStrategy headers.
+     * Gateways (V1 HTTP and V2 RNTBD) reject requests carrying both headers.
+     *
+     * Rules:
+     * 1. Request-level readConsistencyStrategy (requestContext) > client-level readConsistencyStrategy (header)
+     * 2. readConsistencyStrategy > ConsistencyLevel — strip CL when non-DEFAULT readConsistencyStrategy is effective
+     * 3. DEFAULT readConsistencyStrategy is transparent — CL stays
+     *
+     * After this method, the request headers contain at most ONE of the two consistency headers.
+     * GW V1 serializes the surviving header as HTTP; GW V2 (ThinClientStoreModel) encodes it as RNTBD.
+     *
+     * Thread safety: availability-strategy clones share the same header map (shallow copy).
+     * The mutation here (remove CL when readConsistencyStrategy present) is idempotent — concurrent clones
+     * performing the same removal is safe.
+     */
+    private void resolveEffectiveConsistencyHeaders(RxDocumentServiceRequest request) {
+        resolveEffectiveConsistencyHeaders(
+            request.getHeaders(),
+            request.requestContext != null ? request.requestContext.readConsistencyStrategy : null);
+    }
+
+    /**
+     * Core resolution logic — public for direct unit testing from cross-package test classes.
+     * Avoids test drift from duplicated simulation logic.
+     */
+    public static void resolveEffectiveConsistencyHeaders(
+        Map<String, String> headers,
+        ReadConsistencyStrategy requestContextReadConsistencyStrategy) {
+
+        // Determine effective readConsistencyStrategy: requestContext (request-level) takes priority over header (client-level)
+        ReadConsistencyStrategy effectiveReadConsistencyStrategy = null;
+        if (requestContextReadConsistencyStrategy != null
+            && requestContextReadConsistencyStrategy != ReadConsistencyStrategy.DEFAULT) {
+            effectiveReadConsistencyStrategy = requestContextReadConsistencyStrategy;
+        }
+
+        if (effectiveReadConsistencyStrategy == null) {
+            String readConsistencyStrategyHeaderValue = headers.get(HttpConstants.HttpHeaders.READ_CONSISTENCY_STRATEGY);
+            if (!Strings.isNullOrEmpty(readConsistencyStrategyHeaderValue)) {
+                effectiveReadConsistencyStrategy = ReadConsistencyStrategy.DEFAULT; // non-null marker; actual value is in header
+                // Re-parse only to check non-DEFAULT — the header string is authoritative for serialization
+                for (ReadConsistencyStrategy candidate : ReadConsistencyStrategy.values()) {
+                    if (candidate != ReadConsistencyStrategy.DEFAULT
+                        && candidate.toString().equals(readConsistencyStrategyHeaderValue)) {
+                        effectiveReadConsistencyStrategy = candidate;
+                        break;
+                    }
+                }
+            }
+        }
+
+        if (effectiveReadConsistencyStrategy != null && effectiveReadConsistencyStrategy != ReadConsistencyStrategy.DEFAULT) {
+            // readConsistencyStrategy wins — strip ConsistencyLevel to prevent dual-header rejection
+            headers.remove(HttpConstants.HttpHeaders.CONSISTENCY_LEVEL);
+            // Ensure the readConsistencyStrategy header is set (requestContext-level may not have been written to headers yet)
+            headers.put(HttpConstants.HttpHeaders.READ_CONSISTENCY_STRATEGY, effectiveReadConsistencyStrategy.toString());
+        } else if (effectiveReadConsistencyStrategy == ReadConsistencyStrategy.DEFAULT) {
+            // DEFAULT is transparent — remove the sentinel header, let ConsistencyLevel govern
+            headers.remove(HttpConstants.HttpHeaders.READ_CONSISTENCY_STRATEGY);
+        }
+    }
+
     private Mono<RxDocumentServiceResponse> performRequestInternalCore(RxDocumentServiceRequest request, URI requestUri) {
 
         try {
+            // Canonicalize consistency headers before wire serialization.
+            // Both GW V1 (HTTP) and GW V2 (RNTBD via ThinClientStoreModel) read from
+            // request.getHeaders() — this ensures only the winning header reaches the wire.
+            resolveEffectiveConsistencyHeaders(request);
+
             HttpRequest httpRequest = request
                 .getEffectiveHttpTransportSerializer(this)
                 .wrapInHttpRequest(request, requestUri);
@@ -969,6 +1036,39 @@ private Mono<PartitionKeyRange> resolvePartitionKeyRangeByPkRangeIdCore(
        });
     }
 
+    /**
+     * Determines if the effective consistency for this request is Session — needed by
+     * {@link #applySessionToken} to decide whether to attach/remove session tokens.
+     * <p>
+     * Pure read — no side effects, no header mutation, no HashMap copy.
+     * Resolution order: request-level readConsistencyStrategy > client-level readConsistencyStrategy
+     * (header) > consistency-level header > account default.
+     */
+    private boolean isEffectiveSessionConsistency(RxDocumentServiceRequest request) {
+        // Request-level readConsistencyStrategy takes priority
+        if (request.requestContext != null
+            && request.requestContext.readConsistencyStrategy != null
+            && request.requestContext.readConsistencyStrategy != ReadConsistencyStrategy.DEFAULT) {
+            return request.requestContext.readConsistencyStrategy == ReadConsistencyStrategy.SESSION;
+        }
+
+        // Client-level readConsistencyStrategy from header
+        String rcsHeader = request.getHeaders().get(HttpConstants.HttpHeaders.READ_CONSISTENCY_STRATEGY);
+        if (!Strings.isNullOrEmpty(rcsHeader)
+            && !ReadConsistencyStrategy.DEFAULT.toString().equals(rcsHeader)) {
+            return ReadConsistencyStrategy.SESSION.toString().equals(rcsHeader);
+        }
+
+        // Explicit consistency level header
+        String clHeader = request.getHeaders().get(HttpConstants.HttpHeaders.CONSISTENCY_LEVEL);
+        if (!Strings.isNullOrEmpty(clHeader)) {
+            return ConsistencyLevel.SESSION.toString().equalsIgnoreCase(clHeader);
+        }
+
+        // Fall back to account default
+        return this.gatewayServiceConfigurationReader.getDefaultConsistencyLevel() == ConsistencyLevel.SESSION;
+    }
+
     private Mono<Void> applySessionToken(RxDocumentServiceRequest request) {
         Map<String, String> headers = request.getHeaders();
         Objects.requireNonNull(headers, "RxDocumentServiceRequest::headers is required and cannot be null");
@@ -981,8 +1081,11 @@ private Mono<Void> applySessionToken(RxDocumentServiceRequest request) {
             return Mono.empty();
         }
 
-        boolean sessionConsistency = (RequestHelper.getReadConsistencyStrategyToUse(this.gatewayServiceConfigurationReader,
-            request) == ReadConsistencyStrategy.SESSION);
+        // Determine if the effective consistency is Session — needed to decide whether to
+        // attach/remove session tokens. This is a pure read with no side-effects; it does NOT
+        // call RequestHelper.getReadConsistencyStrategyToUse() which mutates x-ms-consistency-level
+        // (a Direct-mode telemetry concern that is harmful in Gateway mode).
+        boolean sessionConsistency = isEffectiveSessionConsistency(request);
 
         if (!Strings.isNullOrEmpty(request.getHeaders().get(HttpConstants.HttpHeaders.SESSION_TOKEN))) {
             if (!sessionConsistency ||

@@ -27,6 +27,24 @@ public static class RntbdHealthCheckResults {
         public static final String SuccessValue = "Success";
     }
 
+    public enum RntbdReadConsistencyStrategy {
+
+        Eventual((byte) 0x01),
+        Session((byte) 0x02),
+        LatestCommitted((byte) 0x03),
+        GlobalStrong((byte) 0x04);
+
+        private final byte id;
+
+        RntbdReadConsistencyStrategy(final byte id) {
+            this.id = id;
+        }
+
+        public byte id() {
+            return this.id;
+        }
+    }
+
     public enum RntbdConsistencyLevel {
 
         Strong((byte) 0x00),
@@ -599,7 +617,8 @@ public enum RntbdRequestHeader implements RntbdHeader {
         GlobalDatabaseAccountName((short) 0x00CE, RntbdTokenType.String, false),
         ThroughputBucket((short)0x00DB, RntbdTokenType.Byte, false),
         PopulateQueryAdvice((short) 0x00DA, RntbdTokenType.Byte, false),
-        HubRegionProcessingOnly((short)0x00EF, RntbdTokenType.Byte , false);
+        HubRegionProcessingOnly((short)0x00EF, RntbdTokenType.Byte , false),
+        ReadConsistencyStrategy((short)0x00FE, RntbdTokenType.Byte, false);
 
         public static final List<RntbdRequestHeader> thinClientHeadersInOrderList = Arrays.asList(
             EffectivePartitionKey,

@@ -18,6 +18,8 @@
 import com.azure.cosmos.implementation.RxDocumentServiceRequest;
 import com.azure.cosmos.implementation.apachecommons.lang.EnumUtils;
 import com.azure.cosmos.implementation.apachecommons.lang.StringUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import com.azure.cosmos.models.IndexingDirective;
 import com.azure.cosmos.models.PriorityLevel;
 import com.fasterxml.jackson.annotation.JsonFilter;
@@ -48,6 +50,7 @@
 
 @JsonFilter("RntbdToken")
 final class RntbdRequestHeaders extends RntbdTokenStream<RntbdRequestHeader> {
+    private static final Logger logger = LoggerFactory.getLogger(RntbdRequestHeaders.class);
 
     private static ImplementationBridgeHelpers.PriorityLevelHelper.PriorityLevelAccessor priorityLevelAccessor() {
         return ImplementationBridgeHelpers.PriorityLevelHelper.getPriorityLevelAccessor();
@@ -139,6 +142,7 @@ private static ImplementationBridgeHelpers.PriorityLevelHelper.PriorityLevelAcce
         this.addThroughputBucket(headers);
         this.addPopulateQueryAdvice(headers);
         this.addHubRegionProcessingOnly(headers);
+        this.addReadConsistencyStrategy(headers);
 
         // Normal headers (Strings, Ints, Longs, etc.)
 
@@ -828,6 +832,37 @@ private void addHubRegionProcessingOnly(final Map<String, String> headers) {
         }
     }
 
+    private RntbdToken getReadConsistencyStrategy() {
+        return this.get(RntbdRequestHeader.ReadConsistencyStrategy);
+    }
+
+    private void addReadConsistencyStrategy(final Map<String, String> headers) {
+        final String value = headers.get(HttpHeaders.READ_CONSISTENCY_STRATEGY);
+
+        if (StringUtils.isNotEmpty(value)) {
+            switch (value) {
+                case "Eventual":
+                    this.getReadConsistencyStrategy().setValue(RntbdConstants.RntbdReadConsistencyStrategy.Eventual.id());
+                    break;
+                case "Session":
+                    this.getReadConsistencyStrategy().setValue(RntbdConstants.RntbdReadConsistencyStrategy.Session.id());
+                    break;
+                case "LatestCommitted":
+                    this.getReadConsistencyStrategy().setValue(RntbdConstants.RntbdReadConsistencyStrategy.LatestCommitted.id());
+                    break;
+                case "GlobalStrong":
+                    this.getReadConsistencyStrategy().setValue(RntbdConstants.RntbdReadConsistencyStrategy.GlobalStrong.id());
+                    break;
+                default:
+                    if (!"Default".equals(value)) {
+                        throw new IllegalArgumentException(
+                            "Unknown ReadConsistencyStrategy value '" + value + "' — cannot encode in RNTBD frame");
+                    }
+                    break;
+            }
+        }
+    }
+
     private void addGlobalDatabaseAccountName(final Map<String, String> headers)
     {
         final String value = headers.get(HttpHeaders.GLOBAL_DATABASE_ACCOUNT_NAME);