Nregion synchronous commit feature

[mbhaskar]

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.

[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]

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]

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.

[Copilot]

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]

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();
	}

[Copilot]

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;
	}