Azure / Azure/azure-sdk-for-java

Cosmos: Add gateway-driven disableCrossRegionalHedging handling (mirror .NET PR #5829)

Open
#49,192 1 comment 0 reactions 0 assignees View on GitHub
Client Cosmos needs-team-attention Service Attention
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.