Azure / Azure/azure-sdk-for-java
[FEATURE REQ] Port hub region caching per partition level from .NET SDK
- Dominant language
- Java
- Stars
- 2.6k
- Forks
- 2.2k
- Avg merge
- 2d 8h
- Merged PRs (30d)
- 178
Description
## Summary
Port the per-partition hub region caching feature from .NET SDK (PR [Azure/azure-cosmos-dotnet-v3#5648](https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5648)) to the Java SDK.
## Background
On single-master accounts encountering repeated 404/1002 (ReadSessionNotAvailable) errors, the SDK should discover the hub region via a 403/3 (WriteForbidden) discovery chain and cache the result per partition. Subsequent requests to the same partition route directly to the cached hub, eliminating redundant discovery round-trips.
## Key Behavior
- After 2 consecutive 404/1002 on a single-master account, set \x-ms-cosmos-hub-region-processing-only\ header
- Non-hub regions return 403/3 (WriteForbidden) — SDK retries to next region (discovery chain)
- Hub region responds with 200 OK — SDK caches hub URI for that partition
- Future requests route directly to cached hub (warm path)
- Works for both PPAF and non-PPAF accounts
- **Must be gated by a feature flag / environment variable** (per Debdatta's guidance)
## .NET Reference
- PR: https://github.com/Azure/azure-cosmos-dotnet-v3/pull/5648
- Key files: ClientRetryPolicy.cs, GlobalPartitionEndpointManagerCore.cs, GatewayStoreModel.cs
## Java SDK Files Likely Affected
- \ClientRetryPolicy.java\
- \GlobalPartitionEndpointManager.java\ / related partition failover classes
- \RxGatewayStoreModel.java\
- \Configs.java\ (feature flag)
## Acceptance Criteria
- [ ] Hub region discovery via 403/3 chain after 2x 404/1002 on single-master
- [ ] Per-partition hub region caching (warm path skips discovery)
- [ ] Feature flag gate (environment variable, disabled by default initially)
- [ ] Works for both PPAF and non-PPAF accounts
- [ ] Unit tests + integration tests
Contributor guide
Assessment
This issue has not been assessed yet.