Azure / Azure/azure-sdk-for-java
Cosmos: Add gateway-driven disableCrossRegionalHedging handling (mirror .NET PR #5829)
- Dominant language
- Java
- Stars
- 2.6k
- Forks
- 2.2k
- Avg merge
- 2d 8h
- Merged PRs (30d)
- 178
Description
## Summary
Cross-SDK parity follow-up from .NET PR [Azure/azure-cosmos-dotnet-v3#5829](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5829). The Java SDK does not currently honor the gateway-driven `disableCrossRegionalHedging` flag on `AccountProperties` (a server-side operator override for cross-region hedging). Without it, an operator flipping the gateway flag will see inconsistent client behavior across .NET vs Java on the same account, defeating the purpose of an operator-level kill-switch.
Filed at the request of @kushagraThapar in PR comment https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5829#pullrequestreview-4293878429 (section M4).
## Background
The .NET PR adds a gateway-driven flag (`AccountProperties.disableCrossRegionalHedging`) that, when set to `true`, disables all cross-region hedging on every request — overriding both per-request and client-level `AvailabilityStrategy` configuration. The flag is read on the existing account-properties refresh path (`GlobalEndpointManager`) and propagated to the hedging strategy reconciler.
Java already has a related-but-distinct **client-side JVM lever**, `COSMOS.IS_READ_AVAILABILITY_STRATEGY_ENABLED_WITH_PPAF`, but no server-driven override.
## Proposed implementation (high level)
Java has the right plumbing already — the `GlobalEndpointManager.perPartitionAutomaticFailoverConfigModifier` callback path is the natural seam:
1. **`AccountProperties` (or equivalent) deserialization** — add a nullable `disableCrossRegionalHedging` field (`Boolean`, i.e., 3-valued: `null` / `true` / `false`).
2. **`GlobalEndpointManager` change-detection** — mirror the .NET PR's `HasValue` guard so an absent property is treated as "no signal" rather than implicit `false`. This is important: without it, a transient gateway response that drops the property will silently re-enable hedging during the exact window the operator most wants it disabled.
3. **Reconcile path** — extend `perPartitionAutomaticFailoverConfigModifier` (or the analogous callback) to receive the disable-hedging signal, stash and restore any customer-configured `AvailabilityStrategy`, and clear the active strategy while the flag is true.
4. **Per-request guard** — the equivalent of `RequestInvokerHandler.AvailabilityStrategy(...)` should short-circuit to `null` when the cached flag is `true`, regardless of per-request `RequestOptions` strategy. This is the absolute-precedence guarantee.
5. **Diagnostics** — surface the gateway-driven suppression in Java's `CosmosDiagnostics` (one-shot per client / per flag-flip is fine).
## Acceptance criteria
- [ ] Java SDK observes the gateway flag and disables cross-region hedging when `true`.
- [ ] Customer client-level opt-out (Java equivalent of `DisablePartitionLevelFailoverClientLevelOverride`) bypasses the flag.
- [ ] An absent property on a subsequent refresh does NOT silently re-enable hedging.
- [ ] Per-request `AvailabilityStrategy` is suppressed when the flag is `true`.
- [ ] Diagnostics entry emitted on first suppression.
- [ ] Parity-test coverage of the four state transitions: `null → true`, `true → false`, `true → null`, `false → true`.
## Cross-references
- .NET PR: https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5829
- Originating reviewer comment: https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5829#pullrequestreview-4293878429 (section M4)
- Python: explicitly out of scope (no SDK-default PPAF hedging in Python; the per-request override path that motivates the knob does not exist there).
Contributor guide
Assessment
This issue has not been assessed yet.