Nregion synchronous commit feature #47757

mbhaskar · 2026-01-20T23:43:55Z

Description

This PR adds support for nregion synchronous commit for less than strong consistency to the SDK

Major changes

Added isNRegionSynchronousCommitEnabled to DatabaseAccount to get if the feature is enabled on the account. This is then populated on the RequestContext for write requests so that it can be read from ConsistencyWriter.
Deserialize GlobalNRegionCommittedGLSN from backend RNTBD response headers
Prior to this, we used to issue barrier requests only for global strong account/requests. This PR introduce barrier request calls for write request when N-Region Synchronous commit is enabled for the account and N-Region Committed LSN is returned for less than strong consistency to enforce barrier writes

Testing

Added unit tests using mock for global strong and n-region barrier requests for success and failure scenarios
Tested manually on a live account that has n-region commit enabled

##Reference
Azure/azure-cosmos-dotnet-v3#5401

All SDK Contribution checklist:

The pull request does not introduce [breaking changes]
CHANGELOG is updated for new features, bug fixes or other significant changes.
I have read the contribution guidelines.

General Guidelines and Best Practices

Title of the pull request is clear and informative.
There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

Pull request includes test coverage for the included changes.

Adding unit tests Refactoring and cleanup

# Conflicts: # sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

Copilot

Pull request overview

This PR adds support for N-region synchronous commit for less than strong consistency levels in the Azure Cosmos DB Java SDK. The feature introduces barrier write requests similar to global strong consistency, but specifically for N-region commit scenarios when the account has this capability enabled.

Changes:

Added deserialization of GlobalNRegionCommittedGLSN header from backend RNTBD responses
Added isNRegionSynchronousCommitEnabled property to DatabaseAccount and propagated it through GlobalEndpointManager and request context
Refactored ConsistencyWriter barrier request logic to support both global strong writes and N-region synchronous commit scenarios
Added comprehensive unit tests for the new barrier request scenarios

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
RntbdConstants.java	Added GlobalNRegionCommittedGLSN response header constant with ID 0x0078
RntbdResponseHeaders.java	Added deserialization support for GlobalNRegionCommittedGLSN header
WFConstants.java	Added GLOBAL_N_REGION_COMMITTED_GLSN backend header constant
StoreResponse.java	Added getNumberOfReadRegions() method to retrieve number of read regions from response headers
ConsistencyWriter.java	Refactored barrier request logic to support both global strong and N-region commit scenarios with dedicated helper methods
BarrierType.java	New enum to distinguish between barrier types (NONE, GLOBAL_STRONG_WRITE, N_REGION_SYNCHRONOUS_COMMIT)
RxDocumentClientImpl.java	Set NRegionSynchronousCommitEnabled flag in request context for write operations
RMResources.java	Added error message for N-region commit barrier not met scenarios
HttpConstants.java	Added sub-status code for N-region commit write barrier failures
GlobalEndpointManager.java	Added method to retrieve N-region synchronous commit enabled status from database account
DocumentServiceRequestContext.java	Added fields for N-region commit enabled flag and barrier type, renamed globalStrongWriteResponse to cachedWriteResponse
DatabaseAccount.java	Added method to check if N-region synchronous commit is enabled on the account
Constants.java	Added ENABLE_N_REGION_SYNCHRONOUS_COMMIT property constant
ConsistencyWriterTest.java	Added comprehensive unit tests for global strong and N-region commit barrier scenarios

Comments suppressed due to low confidence (1)

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/DocumentServiceRequestContext.java:170

The clone method does not copy the two new fields (nRegionSynchronousCommitEnabled and barrierType) added to DocumentServiceRequestContext. When a context is cloned, these fields will be null/default in the cloned instance, which could lead to incorrect behavior during request processing. Add the following assignments to the clone method:
context.nRegionSynchronousCommitEnabled = this.nRegionSynchronousCommitEnabled;
context.barrierType = this.barrierType;

    public DocumentServiceRequestContext clone() {
        DocumentServiceRequestContext context = new DocumentServiceRequestContext();
        context.forceAddressRefresh = this.forceAddressRefresh;
        context.forceRefreshAddressCache = this.forceRefreshAddressCache;
        context.requestChargeTracker = this.requestChargeTracker;
        context.timeoutHelper = this.timeoutHelper;
        context.resolvedCollectionRid = this.resolvedCollectionRid;
        context.sessionToken = this.sessionToken;
        context.quorumSelectedLSN = this.quorumSelectedLSN;
        context.globalCommittedSelectedLSN = this.globalCommittedSelectedLSN;
        context.cachedWriteResponse = this.cachedWriteResponse;
        context.originalRequestConsistencyLevel = this.originalRequestConsistencyLevel;
        context.readConsistencyStrategy = this.readConsistencyStrategy;
        context.resolvedPartitionKeyRange = this.resolvedPartitionKeyRange;
        context.resolvedPartitionKeyRangeForCircuitBreaker = this.resolvedPartitionKeyRangeForCircuitBreaker;
        context.resolvedPartitionKeyRangeForPerPartitionAutomaticFailover = this.resolvedPartitionKeyRangeForPerPartitionAutomaticFailover;
        context.regionIndex = this.regionIndex;
        context.usePreferredLocations = this.usePreferredLocations;
        context.locationIndexToRoute = this.locationIndexToRoute;
        context.regionalRoutingContextToRoute = this.regionalRoutingContextToRoute;
        context.performLocalRefreshOnGoneException = this.performLocalRefreshOnGoneException;
        context.effectivePartitionKey = this.effectivePartitionKey;
        context.performedBackgroundAddressRefresh = this.performedBackgroundAddressRefresh;
        context.cosmosDiagnostics = this.cosmosDiagnostics;
        context.resourcePhysicalAddress = this.resourcePhysicalAddress;
        context.throughputControlRequestContext = this.throughputControlRequestContext;
        context.replicaAddressValidationEnabled = this.replicaAddressValidationEnabled;
        context.endToEndOperationLatencyPolicyConfig = this.endToEndOperationLatencyPolicyConfig;
        context.unavailableRegionsForPartition = this.unavailableRegionsForPartition;
        context.crossRegionAvailabilityContextForRequest = this.crossRegionAvailabilityContextForRequest;
        return context;

Copilot · 2026-01-20T23:54:26Z

.../src/test/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriterTest.java

+    @Test
+    public void isBarrierRequest() {


The test method is missing the TestNG groups attribute that is present on similar test methods in this file. For consistency with the other test methods, this should include @test(groups = "unit").

Copilot · 2026-01-20T23:54:27Z

...e-cosmos/src/main/java/com/azure/cosmos/implementation/directconnectivity/StoreResponse.java

+    public long getNumberOfReadRegions() {
+        int numberOfReadRegions = -1;
+        String numberOfReadRegionsString = this.getHeaderValue(WFConstants.BackendHeaders.NUMBER_OF_READ_REGIONS);
+        if (StringUtils.isNotEmpty(numberOfReadRegionsString)) {
+            try {
+                return Long.parseLong(numberOfReadRegionsString);
+            } catch (NumberFormatException e) {
+                // If value cannot be parsed as Long, return -1.
+            }
+        }
+        return numberOfReadRegions;
+    }


The method declares a return type of long but initializes the local variable numberOfReadRegions as int (-1). This creates a type mismatch. The variable should be declared as long to match the return type and the Long.parseLong operation.

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

.../src/test/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriterTest.java

Copilot · 2026-01-20T23:54:28Z

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RxDocumentClientImpl.java

                            options.setPartitionKeyDefinition(documentCollectionValueHolder.v.getPartitionKey());

                            request.requestContext.setCrossRegionAvailabilityContext(crossRegionAvailabilityContextForRequest);
+                            request.requestContext.setNRegionSynchronousCommitEnabled(this.globalEndpointManager.getNRegionSynchronousCommitEnabled());


The setNRegionSynchronousCommitEnabled is only being set in the createDocument flow (line 2692), but N-region synchronous commit should apply to all write operations (replace, upsert, delete, patch). Based on the pattern where setCrossRegionAvailabilityContext is called in multiple places throughout this file (lines 2253, 2691, 3077, 3377, 3610, 3783, 3972, etc.), setNRegionSynchronousCommitEnabled should be set consistently in all similar places where write operations occur to ensure the feature works correctly for all write request types.

Copilot · 2026-01-20T23:54:28Z

...cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/GlobalEndpointManager.java

    }
+
+    public Boolean getNRegionSynchronousCommitEnabled() {
+        return this.latestDatabaseAccount.isNRegionSynchronousCommitEnabled();


The method could throw a NullPointerException if latestDatabaseAccount is null. The method should check for null and return a safe default value (e.g., false or null) before calling isNRegionSynchronousCommitEnabled(). Similar to how getEffectivePreferredRegions() handles the null case with locking, this method should also handle the null case appropriately.

Suggested change

return this.latestDatabaseAccount.isNRegionSynchronousCommitEnabled();

this.databaseAccountReadLock.lock();

try {

if (this.latestDatabaseAccount == null) {

return null;

}

return this.latestDatabaseAccount.isNRegionSynchronousCommitEnabled();

} finally {

this.databaseAccountReadLock.unlock();

}

Both the comment about having to take a read lock as well as null handling are valid - the former even more important

...zure-cosmos/src/main/java/com/azure/cosmos/implementation/DocumentServiceRequestContext.java

Copilot · 2026-01-20T23:54:28Z

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

+        return request.requestContext.getNRegionSynchronousCommitEnabled()
+            && !this.useMultipleWriteLocations
+            && StringUtils.isNotEmpty(response.getHeaderValue(WFConstants.BackendHeaders.GLOBAL_N_REGION_COMMITTED_GLSN))
+            && Long.parseLong(response.getHeaderValue(WFConstants.BackendHeaders.GLOBAL_N_REGION_COMMITTED_GLSN)) != -1
+            && response.getNumberOfReadRegions() > 0;


The method isNRegionSynchronousCommitBarrierRequest could throw a NumberFormatException when parsing the GLOBAL_N_REGION_COMMITTED_GLSN header value on line 481. The check on line 480 only verifies that the string is not empty, but doesn't validate that it's a valid parseable long. If the header contains an invalid numeric value, it will cause an unhandled exception. The parsing should be wrapped in a try-catch block, or the validation should be more robust.

Suggested change

return request.requestContext.getNRegionSynchronousCommitEnabled()

&& !this.useMultipleWriteLocations

&& StringUtils.isNotEmpty(response.getHeaderValue(WFConstants.BackendHeaders.GLOBAL_N_REGION_COMMITTED_GLSN))

&& Long.parseLong(response.getHeaderValue(WFConstants.BackendHeaders.GLOBAL_N_REGION_COMMITTED_GLSN)) != -1

&& response.getNumberOfReadRegions() > 0;

String globalCommittedGlsnHeader =

response.getHeaderValue(WFConstants.BackendHeaders.GLOBAL_N_REGION_COMMITTED_GLSN);

if (!request.requestContext.getNRegionSynchronousCommitEnabled()

|| this.useMultipleWriteLocations

|| StringUtils.isEmpty(globalCommittedGlsnHeader)

|| response.getNumberOfReadRegions() <= 0) {

return false;

}

try {

long globalCommittedGlsnValue = Long.parseLong(globalCommittedGlsnHeader);

return globalCommittedGlsnValue != -1;

} catch (NumberFormatException e) {

// Malformed header value: treat as no barrier instead of throwing.

return false;

}

…ntation/DocumentServiceRequestContext.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

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

FabianMeiswinkel · 2026-01-22T11:14:41Z

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

-    private Mono<Boolean> waitForWriteBarrierAsync(
+    private String getErrorMessageForBarrierRequest(RxDocumentServiceRequest request) {
+        if (request.requestContext.getBarrierType() == BarrierType.N_REGION_SYNCHRONOUS_COMMIT) {
+            return String.format("ConsistencyWriter: Write barrier has not been met for n region synchronous commit request. SelectedGlobalCommittedLsn: %s",


Log value of n - how many regions have to commit is configurable (should be part of the account metadata)?

FabianMeiswinkel · 2026-01-22T11:15:53Z

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

+            HttpConstants.SubStatusCodes.GLOBAL_STRONG_WRITE_BARRIER_NOT_MET);
+    }
+
+    boolean isBarrierRequest(RxDocumentServiceRequest request, StoreResponse response) {


This function has side effects - please reflect that in the name. The isXXX naming pattern is usually only used for functions withut any side-effects.

My preference would probably be to just have a function "calculating" the BarrierType - and then use != NONE as condition for the caller whether isBarrierRequest is set and then modifcy the RequestConetxt there?

jeet1995 · 2026-01-22T22:46:05Z

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

            globalCommittedLsn.v = Long.parseLong(headerValue);
        }
+        else if ((headerValue = response.getHeaderValue(WFConstants.BackendHeaders.GLOBAL_N_REGION_COMMITTED_GLSN)) != null) {
+            globalCommittedLsn.v = Long.parseLong(headerValue);


I was wondering if we need a separate property in the diagnostic string for N-Region Committed LSN (to represent the LSN) and also account-level N-Region Commit enablement.

jeet1995 · 2026-01-22T22:47:52Z

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java


                    if (!v) {
-                        logger.info("ConsistencyWriter: Write barrier has not been met for global strong request. SelectedGlobalCommittedLsn: {}", request.requestContext.globalCommittedSelectedLSN);
+                        logger.info(this.getErrorMessageForBarrierRequest(request));


I wonder if error (if unrecoverable) or warn (if recoverable) is the better choice here (not introduced by this PR but nevertheless).

jeet1995 · 2026-01-22T23:12:35Z

...smos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

+            request.requestContext.setBarrierType(BarrierType.N_REGION_SYNCHRONOUS_COMMIT);
+            return true;
+        }
+        request.requestContext.setBarrierType(BarrierType.NONE);


What is the barrier expectation or that of wrapping write operation when is isNRegionSynchronousCommitBarrierRequest evaluates to false and barrier is required due to some weird response from the backend? Are we failing the wrapping write in a certain way?

mbhaskar added 5 commits January 9, 2026 18:44

Adding support for nregion commit feature

793b176

Adding nregion header serialization in RNTBD

1351016

Adding unit tests Refactoring and cleanup

Cleaning up test

c87d4ad

Merge branch 'master' into nregioncommit

9633801

# Conflicts: # sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/directconnectivity/ConsistencyWriter.java

Test cleanup and refactoring

1a8e02c

Copilot AI review requested due to automatic review settings January 20, 2026 23:43

mbhaskar requested review from a team and kirankumarkolli as code owners January 20, 2026 23:43

github-actions bot added the Cosmos label Jan 20, 2026

Copilot started reviewing on behalf of mbhaskar January 20, 2026 23:44 View session

Copilot AI reviewed Jan 20, 2026

View reviewed changes

mbhaskar and others added 5 commits January 20, 2026 16:14

Update sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/impleme…

1b17110

…ntation/DocumentServiceRequestContext.java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update code doc

e703663

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

adding unit test group

4c025be

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

Fixing imports issue caused by copilot

c9b55ef

fixing tests

5a85467

FabianMeiswinkel reviewed Jan 22, 2026

View reviewed changes

jeet1995 reviewed Jan 22, 2026

View reviewed changes

-        return this.latestDatabaseAccount.isNRegionSynchronousCommitEnabled();
+        this.databaseAccountReadLock.lock();
+        try {
+            if (this.latestDatabaseAccount == null) {
+                return null;
+            }
+            return this.latestDatabaseAccount.isNRegionSynchronousCommitEnabled();
+        } finally {
+            this.databaseAccountReadLock.unlock();
+        }

-        return request.requestContext.getNRegionSynchronousCommitEnabled()
-            && !this.useMultipleWriteLocations
-            && StringUtils.isNotEmpty(response.getHeaderValue(WFConstants.BackendHeaders.GLOBAL_N_REGION_COMMITTED_GLSN))
-            && Long.parseLong(response.getHeaderValue(WFConstants.BackendHeaders.GLOBAL_N_REGION_COMMITTED_GLSN)) != -1
-            && response.getNumberOfReadRegions() > 0;
+        String globalCommittedGlsnHeader =
+            response.getHeaderValue(WFConstants.BackendHeaders.GLOBAL_N_REGION_COMMITTED_GLSN);
+        if (!request.requestContext.getNRegionSynchronousCommitEnabled()
+            || this.useMultipleWriteLocations
+            || StringUtils.isEmpty(globalCommittedGlsnHeader)
+            || response.getNumberOfReadRegions() <= 0) {
+            return false;
+        }
+        try {
+            long globalCommittedGlsnValue = Long.parseLong(globalCommittedGlsnHeader);
+            return globalCommittedGlsnValue != -1;
+        } catch (NumberFormatException e) {
+            // Malformed header value: treat as no barrier instead of throwing.
+            return false;
+        }

Nregion synchronous commit feature #47757

Are you sure you want to change the base?

Nregion synchronous commit feature #47757

Uh oh!

Conversation

mbhaskar commented Jan 20, 2026

Description

Major changes

Testing

All SDK Contribution checklist:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeet1995 Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jeet1995 Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jeet1995 Jan 22, 2026 •

edited

Loading

jeet1995 Jan 22, 2026 •

edited

Loading