Block ReadConsistencyStrategy in Gateway modes — Direct-only until e2e support added

[Copilot]

• Block ReadConsistencyStrategy in Gateway mode at build time (CosmosClientBuilder.validateConfig)
• Block ReadConsistencyStrategy in Gateway mode at request time (RxDocumentClientImpl.validateNonDefaultReadConsistencyStrategy)
• Rename validateAndLogNonDefaultReadConsistencyStrategy → validateNonDefaultReadConsistencyStrategy at all call sites
• Unit tests for builder-level validation (CosmosClientBuilderTest)
• CHANGELOG entry
• Unit tests for ReadConsistencyStrategy on all Cosmos*RequestOptions types (ReadConsistencyStrategyRequestOptionsTest)
• E2E test class ReadConsistencyStrategyForGatewayE2ETests with "thin-client-multi-region" and "multi-region" TestNG groups
• Move GatewayVariant enum to TestSuiteBase as a public utility
• Revert .gitignore from azure-cosmos-tests
• Move client.close() into finally blocks in CosmosClientBuilderTest
• Fix RetryContextOnDiagnosticTest.throttlingExceptionGatewayModeScenario — remove incompatible ReadConsistencyStrategy.EVENTUAL usage in Gateway mode test

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[FEATURE REQ] [Gateway V1/V2] Block ReadConsistencyStrategy in all Gateway modes — Direct-only until e2e support added</issue_title>
<issue_description># Issue

When ReadConsistencyStrategy is configured on requestOptions and the CosmosClient is using Gateway mode, the end-to-end behavior is not deterministic.

Ask

The ask is to "block" on CosmosClient, the ReadConsistencyStrategy option when such CosmosClient instance is configured with Gateway mode (either client-level or request-level setting).

References

See:

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

Lines 1871 to 1882 in 0bcde7e

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

Things to keep in mind

See: FaultInjectionServerErrorRuleOnGatewayV2Tests for running Gateway V2 tests. Ideally, we should stick to a single test class but using two different TestNG groups - one for thin-client-multi-region (use existing) and for multi-region. We also have various types of request options, so blocking ReadConsistencyStrategy should be all encompassing.</issue_description>

<agent_instructions>Use a branch naming convention such as AzCosmos_*</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [FEATURE REQ] [Gateway V1/V2] Block ReadConsistencyStrategy in all Gateway modes — Direct-only until e2e support added #48110

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[jeet1995]

@copilot when you're done, please also run /azp run java - cosmos - tests

[Copilot]

@copilot when you're done, please also run /azp run java - cosmos - tests

All code changes are complete and pushed (commit d049f6f). I'm unable to trigger Azure Pipelines directly — could you run /azp run java - cosmos - tests on the PR?

[jeet1995]

@copilot Ensure unit test coverage across all Cosmos(*)RequestOptions. I do not see request options level coverage.

[jeet1995]

@copilot Ensure end-to-end test coverage in ReadConsistencyStrategyForGatewayE2ETests. Use "thin-client-multi-region" and "multi-region" TestNG groups for Gateway V2 and Gateway V1 respectively. See FaultInjectionServerErrorRuleOnGatewayV2Tests as an example.

[Copilot]

@copilot Ensure unit test coverage across all Cosmos(*)RequestOptions. I do not see request options level coverage.

Added ReadConsistencyStrategyRequestOptionsTest (commit 32ac345) with 30 unit tests covering set/getReadConsistencyStrategy across all five Cosmos*RequestOptions types:

• CosmosItemRequestOptions
• CosmosQueryRequestOptions
• CosmosChangeFeedRequestOptions
• CosmosReadManyRequestOptions
• CosmosRequestOptions

Each type is tested with all 5 strategies (DEFAULT, EVENTUAL, SESSION, LATEST_COMMITTED, GLOBAL_STRONG) plus null reset.

[Copilot]

@copilot Ensure end-to-end test coverage in ReadConsistencyStrategyForGatewayE2ETests. Use "thin-client-multi-region" and "multi-region" TestNG groups for Gateway V2 and Gateway V1 respectively. See F...

Added ReadConsistencyStrategyForGatewayE2ETests in commit 4ebf596 with E2E test coverage using both TestNG groups:

• multi-region — Gateway V1 (via clientBuildersWithGateway())
• thin-client-multi-region — Gateway V2 (via clientBuildersWithGatewayAndHttp2())

Tests cover all request options types with all 4 non-DEFAULT strategies:

• readItem → CosmosItemRequestOptions
• queryItems → CosmosQueryRequestOptions
• queryChangeFeed → CosmosChangeFeedRequestOptions
• readMany → CosmosReadManyRequestOptions

Plus positive tests for DEFAULT and null strategies.

[jeet1995]

@copilot - this seems a utility, please move it to TestSuiteBase.

[Copilot]

Moved GatewayVariant to TestSuiteBase as a public enum in commit e53d787.

[jeet1995]

@copilot - please revert this and don't produce or stage any test-output

[Copilot]

Reverted in b148687. The .gitignore file has been removed from azure-cosmos-tests.

[jeet1995]

@copilot - move client.close() into a finally block.

[Copilot]

Done in 423261a — moved client.close() into finally blocks across all four test methods in the file.

[jeet1995]

@copilot - please fix - RetryContextOnDiagnosticTest.throttlingExceptionGatewayModeScenario � IllegalArgument ReadConsistencyStrategy Eventual is not supported in Gateway mode. ReadConsistencyStrategy is only supported when using DIRECT connection mode.

[Copilot]

@copilot - please fix - RetryContextOnDiagnosticTest.throttlingExceptionGatewayModeScenario � IllegalArgument ReadConsistencyStrategy Eventual is not supported in Gateway mode. Read...

Fixed in 4a41c1f — removed the options.setReadConsistencyStrategy(ReadConsistencyStrategy.EVENTUAL) call from throttlingExceptionGatewayModeScenario since that test uses Gateway mode. The ReadConsistencyStrategy setting was not relevant to the test's purpose (testing retry context on throttling diagnostics).