Effective Preferred Locations

[tvaron3]

Background

Preferred locations is an option set on the cosmos client. It indicates to the SDK in what priority to route requests.
Example

• Account Regions (these are the ones that appear in portal): East US, East US 2, West US, West US 2
• Preferred Locations: East US, West US, West US 2
• Read: Requests will be routed to East US first. If for some reason, the requests fail with a retrieable error or status code, then the requests will be retried on West US. If the requests fail again, then the requests will be retried on West US 2. Note that requests will never go to East US 2 because it is not part of the preferred locations.
• Writes: For single write accounts, writes will go to the write region regardless of preferred locations set. For multi write accounts, writes will go to the preferred locations in order.

Problem

Previously to this pr, if no preferred locations were passed into the cosmos client then the SDK would route requests only to the hub region for single write accounts. For multi-write accounts, the SDK would route requests only to the endpoint passed in through the client. This is undesirable because it would be opting out customers by default to an availability feature.

Solution

If no preferred locations and the global endpoint are passed into the cosmos client, then the SDK will populate it using the account regions. If a regional endpoint is passed in, the existing behavior will be kept.

Note: This is a breaking change for customers using bounded staleness consistency.

Relevant Issue

• Effective Preferred Regions When No Preferred Regions Are Specified #39376

[azure-sdk]

API change check

API changes are not detected in this pull request.

[tvaron3]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[tvaron3]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[simorenoh]

love the way the test is made as well, thanks Tomas!

[jeet1995]

All requests will be routed to East US first. If for some reason, the requests fail with a retriable error or status code, then the requests will be retried on West US. If the requests fail again, then the requests will be retried on West US 2. Note that requests will never go to East US 2 because it is not part of the preferred locations.

I think you need to disambiguate between how reads and writes behave.

[jeet1995]

Another aspect is testing - it would be good to add coverage in our retry policy tests when the client isn't configured with preferred locations - 503, 408, 404:1002 - all have cross-region retry semantics.