Fix background database account refresh stopping in multi-writer accounts

[jeet1995]

Problem

The GlobalEndpointManager background refresh timer silently stops in multi-writer accounts, preventing the SDK from detecting topology changes (e.g., multi-write to single-write transitions).

Root Cause

In refreshLocationPrivateAsync(), when LocationCache.shouldRefreshEndpoints() returns false, the timer is never restarted:

} else {
    logger.debug("shouldRefreshEndpoints: false, nothing to do.");
    this.isRefreshing.set(false);
    return Mono.empty(); // timer dies here
}

For multi-writer accounts, shouldRefreshEndpoints() returns false when the preferred write endpoint matches the current primary -- a steady-state condition. Once that happens, no further background refreshes occur for the lifetime of the client. Bug has existed since PR #6139 (Nov 2019, point #4 in description).

Behavioral Difference with .NET SDK

The .NET SDK (azure-cosmos-dotnet-v3) handles this correctly in StartLocationBackgroundRefreshLoop():

if (!this.locationCache.ShouldRefreshEndpoints(out bool canRefreshInBackground))
{
    if (!canRefreshInBackground)
    {
        this.isBackgroundAccountRefreshActive = false;
        return; // only stops when canRefreshInBackground is explicitly false
    }
}
// otherwise: delay -> refresh -> loop again

The .NET loop only terminates when canRefreshInBackground is explicitly false -- it continues even when ShouldRefreshEndpoints() returns false.

Fix

Add startRefreshLocationTimerAsync() to the else branch of refreshLocationPrivateAsync():

} else {
    logger.debug("shouldRefreshEndpoints: false, nothing to do.");
    if (!this.refreshInBackground.get()) {
        this.startRefreshLocationTimerAsync();
    }
    this.isRefreshing.set(false);
    return Mono.empty();
}

Unit Tests

6/6 pass:

• backgroundRefreshForMultiMaster: Updated assertion from assertFalse to assertTrue -- timer must keep running
• backgroundRefreshDetectsTopologyChangeForMultiMaster: New -- simulates MW to SW transition via mock, verifies writableLocations update from 2 to 1

Live DR Drill Validation

Test Configuration

Setting	Value
Account	bgrefresh-mw-test-440 (ephemeral tenant)
Regions	East US (hub) + West US
Endpoint	Global (bgrefresh-mw-test-440.documents.azure.com)
Preferred region	West US
Connection mode	DIRECT (RNTBD)
Background refresh	30s (overridden via COSMOS.UNAVAILABLE_LOCATIONS_EXPIRATION_TIME_IN_SECONDS=30, default: 300s/5min)
SDK	azure-cosmos 4.80.0-beta.1 (patched)

Patched vs Unpatched

Metric	Patched	Unpatched
Background refreshes (51 min)	103	0
Metadata transitions detected	9/9	0/9
Reads	305	~20
Errors	0	0 (but topology changes never detected)

Drill 1: MW to SW to MW Transition

Both transitions detected. writableLocations changed [EUS, WUS] to [EUS] to [EUS, WUS] with ~3 min / ~2 min metadata propagation lag.

Drill 2: Region Removal + Re-add

Detected. readableLocations shrank from [EUS, WUS] to [EUS] then restored. DIRECT mode note: reads continued via existing RNTBD connections even after region metadata removal (by design).

Drill 3: Failover Priority Change

All transitions detected. failover-priority-change propagated fastest (~1 min vs ~5 min for region removal).

Summary

Changes

• 1 file changed, 10 insertions (GlobalEndpointManager.java)
• 1 file changed, 50 insertions, 1 deletion (GlobalEndPointManagerTest.java)

[jeet1995]

DR Drill Test Results

Test Configuration

Setting	Value
Account	bgrefresh-mw-test-440 (ephemeral tenant)
Regions	East US (hub) + West US
Endpoint	Global (bgrefresh-mw-test-440.documents.azure.com)
Preferred region	West US
Connection mode	DIRECT (RNTBD)
Background refresh	30s (overridden via COSMOS.UNAVAILABLE_LOCATIONS_EXPIRATION_TIME_IN_SECONDS=30, default: 300s)
SDK	azure-cosmos 4.80.0-beta.1 (patched with this fix)

Summary

Metric	Patched	Unpatched
Background refreshes (51 min)	103	0
Metadata transitions detected	9/9	0/9
Read errors	0	0 (but topology changes never detected)
Read availability	100%	100% (stuck on stale routing)

Per-Drill Results

Drill 1: MW→SW→MW Transition — Both transitions detected (3 min / 2 min metadata propagation lag)

Drill 2: Region Removal + Re-add — Detected. DIRECT mode note: reads continue via existing RNTBD connections even after metadata removal.

Drill 3: Failover Priority Change — All transitions detected. Fastest propagation (~1 min vs ~5 min for region removal).

Summary

Full report: dr-drill-report.md