[Cosmos][WIP]: Normalize region names passed as preferred or exclude regions.

[jeet1995]

Problem

Customers passing region names in non-canonical forms (e.g., west us 3 or westus3 instead of West US 3) hit routing issues. The Java SDK stores region names in different representations (lowercased in maps, original case in lists), and some code paths use case-sensitive String.equals()/List.contains() — causing mismatches between user-provided and server-returned region names.

The .NET SDK solves this with a RegionNameMapper that normalizes all region input to canonical form at client construction. The Java SDK lacked this.

Core approach

Normalization: strip spaces + lowercase → lookup in a static map of known Azure regions → return canonical form.

Input	After strip+lower	Lookup result
westus3	westus3	West US 3 ✓
west us 3	westus3	West US 3 ✓
WEST US 3	westus3	West US 3 ✓
West US 3	westus3	West US 3 ✓ (no-op)

Escape hatch for unknown regions: If a region is not in the static map (e.g., a brand-new Azure region not yet compiled into the SDK), the input is returned as-is. This works because LocationCache applies toLowerCase() and uses CaseInsensitiveMap for all endpoint lookups — so even unknown regions match correctly as long as the customer's input has the same words as the server response (any casing works, spaces are optional for known regions only).

No deduplication: If a customer passes ["westus3", "West US 3"], both normalize to "West US 3" and the list will contain two identical entries. This is intentional — duplicate preferred regions are an obvious misconfiguration that the customer should fix, not something the SDK should silently mask.

Changes

RegionUtils.java (renamed from RegionNameToRegionIdMap.java) — single source of truth

• Renamed to RegionUtils to better reflect its dual role: region ID mapping + region name normalization.
• Region ID map: synced with the authoritative regionToIdMapping from Settings.xml (IDs 1–124). Used only for session token region-level progress tracking (localLsn).
• Region name normalization: getCosmosDBRegionName(String) — static normalizer. Canonical names derived from the ID map. Unknown regions passed through as-is.
• normalizeRegionNames(List<String>) and containsRegionIgnoreCase(List<String>, String) — utilities for batch normalization and case-insensitive region membership checks (moved out of LocationCache).
• Built NORMALIZED_REGION_NAME_TO_REGION_ID_MAPPINGS programmatically from the ID map (was manually duplicated before).

ConnectionPolicy.setPreferredRegions()

• Normalize each region via RegionUtils.getCosmosDBRegionName() at entry.
• Unknown regions not in the static map are passed through as-is.

LocationCache.java

• Constructor: apply RegionUtils.getCosmosDBRegionName() before toLowerCase() (defense-in-depth).
• Bug fix (line 502): replaced case-sensitive List.contains() with RegionUtils.containsRegionIgnoreCase() in PPCB reevaluate logic — was causing excluded regions to be re-added as retry targets when casing didn't match.
• Normalize user-configured exclude regions via RegionUtils.normalizeRegionNames() before comparison in getApplicableRegionRoutingContexts().

Tests

Unit tests (run locally, all pass)

• 44 RegionUtilsNormalizationTest — case variants, space removal, passthrough, null/empty, unknown regions
• 38 LocationCacheTest — 32 existing + 6 new integration tests with real Azure region names (preferred region and exclude region normalization)
• 1 RegionUtilsTests — existing ID map consistency check

E2E tests (run in CI)

• ExcludeRegionTests: 3 new tests (15 cases via DataProvider) — client with space-stripped preferred regions, exclude with space-stripped/uppercase names
• FaultInjectionWithAvailabilityStrategyTestsBase: 1 new test — client with space-stripped preferred regions + eager availability strategy
• PerPartitionCircuitBreakerE2ETests: 1 new test — client with space-stripped preferred regions + PPCB routing validation

[jeet1995]

/azp run java - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[jeet1995]

@sdkReviewAgent

[Copilot]

Pull request overview

This PR addresses Cosmos DB routing mismatches caused by non-canonical Azure region name inputs by introducing centralized region normalization and applying it to preferred/excluded region handling across the Cosmos Java SDK routing stack.

Changes:

• Added RegionUtils as the single source of truth for region ID mappings and canonical region name normalization, and updated call sites to use it.
• Normalized preferred/excluded regions in ConnectionPolicy and LocationCache, including a fix for a case-sensitive exclude-region check in PPCB reevaluation logic.
• Added/updated unit and E2E tests to validate routing behavior with non-canonical region inputs and updated the Cosmos changelog entry.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RxDocumentClientImpl.java	Switches region ID lookup to RegionUtils.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/routing/RegionUtils.java	Introduces region normalization + region ID mapping utilities.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/routing/RegionNameToRegionIdMap.java	Removes the old region mapping class in favor of RegionUtils.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/routing/LocationCache.java	Normalizes excluded regions and fixes PPCB exclude-region comparison behavior.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/PartitionScopedRegionLevelProgress.java	Updates region ID/name lookups to RegionUtils.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/ConnectionPolicy.java	Normalizes preferred regions at configuration time.
sdk/cosmos/azure-cosmos/CHANGELOG.md	Documents the normalization + PPCB exclude-region fix.
sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/PerPartitionCircuitBreakerE2ETests.java	Adds E2E coverage for PPCB routing with non-canonical preferred regions.
sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/implementation/routing/RegionUtilsNormalizationTest.java	Adds unit coverage for normalization behavior.
sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/implementation/routing/LocationCacheTest.java	Adds integration-style unit tests for preferred/exclude region normalization with real region names.
sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/implementation/RegionUtilsTests.java	Updates the existing mapping-consistency test to the new RegionUtils.
sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/FaultInjectionWithAvailabilityStrategyTestsBase.java	Adds E2E validation for availability strategy routing with non-canonical preferred regions.
sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/ExcludeRegionTests.java	Adds E2E coverage for non-canonical preferred/exclude region inputs.

[xinlian12]

@sdkReviewAgent

[xinlian12]

I am wondering whether we should fallback to normalized version when not found from the map. Even in globalEndpointManager, we just use the normalized version for findings the regional endpoint

[xinlian12]

should we also change to use RegionUtils for GlobalEndpointManager as well

[xinlian12]

🟢 Suggestion — Forward Compatibility: Unknown regions with space variants won't match

For unknown regions (not in the static map), getCosmosDBRegionName returns the input as-is. This means two variant spellings of the same unknown region won't match if they differ by spaces:

• Customer passes preferredRegions = ["futureregion"]
• Server returns "Future Region" → stored as "future region" in addRoutingContexts
• Preferred location "futureregion" ≠ "future region" → region not matched

The PR description acknowledges this: "spaces are optional for known regions only." The defense-in-depth via CaseInsensitiveMap + toLowerCase() handles case differences for unknown regions, but not space differences.

If forward compatibility for space-stripped unknown regions is desired, the fallback could return the normalized form instead of the original:

// Instead of: return regionName;
return normalized; // lowercase + no-spaces, matches server after toLowerCase

This would make "futureregion" and "Future Region" both collapse to "futureregion", matching in the lowercased endpoint map. The tradeoff: diagnostic logs would show the normalized form instead of the user's original input.

⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.

[xinlian12]

🟡 Recommendation — Maintenance: Derive REGION_ID_TO_NORMALIZED_REGION_NAME_MAPPINGS programmatically

This map is still 124 hand-maintained entries, while NORMALIZED_REGION_NAME_TO_REGION_ID_MAPPINGS (same data, inverse direction) was correctly refactored to be derived programmatically from REGION_NAME_TO_REGION_ID_MAPPINGS. The inconsistency creates a maintenance trap: when a new region is added to REGION_NAME_TO_REGION_ID_MAPPINGS, a contributor must also remember to update this manual map. Two of four maps auto-derive; this one doesn't.

The existing test regionIdToRegionNameConsistency catches inconsistencies, but a pit-of-success design would eliminate the risk entirely:

static {
    Map<Integer, String> idToNormalized = new HashMap<>();
    Map<String, Integer> normalizedToId = new HashMap<>();
    for (Map.Entry<String, Integer> entry : REGION_NAME_TO_REGION_ID_MAPPINGS.entrySet()) {
        String normalized = entry.getKey().toLowerCase(Locale.ROOT).replace(" ", "");
        normalizedToId.put(normalized, entry.getValue());
        idToNormalized.putIfAbsent(entry.getValue(), normalized);
    }
    NORMALIZED_REGION_NAME_TO_REGION_ID_MAPPINGS = Collections.unmodifiableMap(normalizedToId);
    REGION_ID_TO_NORMALIZED_REGION_NAME_MAPPINGS = Collections.unmodifiableMap(idToNormalized);
}

This eliminates ~130 lines of duplicated data and makes REGION_NAME_TO_REGION_ID_MAPPINGS the true single source of truth.

⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.

[xinlian12]

🟡 Recommendation — Testing: No unit tests for containsRegionIgnoreCase and normalizeRegionNames

These two new public utility methods have zero direct unit tests. containsRegionIgnoreCase is the direct replacement for the buggy List.contains() — it deserves focused tests documenting its contract. normalizeRegionNames silently drops null elements from the input (reducing list size), which is a behavioral contract that should be explicitly tested.

Suggested additions to RegionUtilsNormalizationTest:

// containsRegionIgnoreCase
assertThat(RegionUtils.containsRegionIgnoreCase(
    Arrays.asList("westus3"), "West US 3")).isTrue();
assertThat(RegionUtils.containsRegionIgnoreCase(
    Arrays.asList("West US 3"), "WEST US 3")).isTrue();
assertThat(RegionUtils.containsRegionIgnoreCase(
    null, "anything")).isFalse();
assertThat(RegionUtils.containsRegionIgnoreCase(
    Arrays.asList("East US"), "unknownRegion")).isFalse();

// normalizeRegionNames
assertThat(RegionUtils.normalizeRegionNames(
    Arrays.asList("westus3", "east us")))
    .containsExactly("West US 3", "East US");
assertThat(RegionUtils.normalizeRegionNames(null)).isEmpty();
assertThat(RegionUtils.normalizeRegionNames(
    Arrays.asList("East US", null, "westus3")))
    .containsExactly("East US", "West US 3"); // null dropped

⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.

[xinlian12]

🟡 Recommendation — Correctness: containsRegionIgnoreCase NPE if list contains null elements

If region is null, getCosmosDBRegionName(null) returns null (via the StringUtils.isEmpty guard), then null.equalsIgnoreCase(normalizedTarget) throws NullPointerException.

Current callers are safe — the sole production caller at LocationCache:506 passes a list already processed by normalizeRegionNames(), which filters nulls. But this is a package-visible utility method whose contract doesn't document the null-element restriction. A future caller could hit this.

for (String region : regions) {
    if (region != null && getCosmosDBRegionName(region).equalsIgnoreCase(normalizedTarget)) {
        return true;
    }
}

⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.

[xinlian12]

🟡 Recommendation — Testing: No regression test for the PPCB List.contains() bug fix

This line is the actual bug fix described in the PR — replacing case-sensitive List.contains(internalExcludeRegion) with RegionUtils.containsRegionIgnoreCase(userConfiguredExcludeRegions, internalExcludeRegion). It prevents excluded regions from being silently re-added as retry targets when casing didn't match.

However, no test exercises this specific code path. The reevaluate() method is only entered when applicableRegionalRoutingContexts.size() < 2 AND preferredRoutingContexts.size() > 1 AND PPCB internal exclude regions are present. None of the 6 new LocationCacheTest normalization tests pass internalExcludeRegions. The E2E PPCB test (nonCanonicalPreferredRegions_ppcbShouldStillRouteCorrectly) does a basic create+read without fault injection, so it never triggers the circuit breaker or enters reevaluate.

A targeted regression test would: (1) set up user-configured exclude regions in non-canonical form (e.g., "westus3"), (2) provide internalExcludeRegions in lowercased canonical form (e.g., "west us 3"), (3) trigger the reevaluate path (ensure only 1 applicable endpoint remains), (4) assert the internally excluded region is NOT re-added when it matches the user's exclude list after normalization.

Without this, a future refactor could reintroduce the case-sensitive contains() without breaking any test.

⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.

[xinlian12]

✅ Review complete (58:11)

Posted 5 inline comment(s).

_{Steps: ✓ context, correctness, cross-sdk, design, history, past-prs, synthesis, test-coverage}

[jeet1995]

/azp run java - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).