Summary

Drivers have no supported way to deterministically prefer mongos endpoints in a designated region during normal operations while automatically and transparently failing over to another region's mongos endpoints when the preferred region becomes unavailable; without any connection string change, application restart, or intervention at the moment of failover.

localThresholdMS is the closest existing mechanism, but it is probabilistic: the driver builds a latency window around the fastest host and randomly load-balances across every candidate inside that window, so a non-preferred-region mongos can still be selected on any given operation. Read preference `tagSets` don't help either, since they govern replica set member selection and have no effect on which mongos a driver picks in a sharded topology.

We are trying to achieve deterministic, driver-level regional affinity for mongos selection: 100% of traffic to the preferred region while it's healthy, automatic tiered fallback when it isn't, and automatic recovery once it's healthy again - with zero manual or automated intervention required at the moment of failover.

Motivation

Who is the affected end user?

Operators of multi-region sharded clusters with an active/DR (or multi-cloud, multi-region) topology - both self-hosted Enterprise Advanced deployments and Atlas. The pattern is common in regulated industries (e.g. financial services) running mission-critical, latency-sensitive workloads across two or more datacenters/regions.

How does this affect the end user?

Affected users face a forced choice between two unacceptable options: (1) include all-region mongos endpoints and accept non-deterministic cross-region routing and latency variance in steady state, or (2) exclude non-preferred-region endpoints and accept a connection-string change as an application-impacting step at DR time. Neither preserves an expectation of seamless, zero-downtime failover for sharded clusters. This is more than annoyance - for latency-sensitive, mission-critical workloads it undermines a core availability commitment made to the business running on top of the cluster.

How likely is it that this problem or use case will occur?

Main path. Any sharded cluster deployed across more than one region/datacenter with multiple mongos instances is exposed to this by default - cross-region routing is the expected outcome of current latency-window selection whenever two regions fall within (or near) the same latency window, not a rare misconfiguration.

If the problem does occur, what are the consequences and how severe are they?

Primarily a performance concern in steady state (added latency, latency variance, and in multi-cloud cases, cross-cloud egress cost) rather than an outage - operations still complete. However, for workloads with strict latency SLAs (e.g. payments processing), sustained cross-region routing can translate into SLA violations. Separately, the DR-time workaround (connection string change) introduces a real availability regression risk: if that step is missed, delayed, or mishandled, failover can be materially slower or require an application restart, which is the specific outcome mission-critical users are trying to avoid entirely.

Is this issue urgent?

Yes. This is a re-escalation of a previously closed request (DRIVERS-3191, Won't Do, P2), now raised again due to renewed field pressure from enterprise accounts and at least one case where latency-sensitive workloads are scheduled to move onto affected clusters in the near term. There is no hard contractual deadline captured yet, but the business context has materially increased priority relative to the original closure.

Is this ticket required by a downstream team?

Likely yes, from Atlas - the related proposed spec was originally motivated by multi-cloud Atlas sharded clusters. Any implementation should be coordinated with Atlas rather than scoped as EA-only, since both surfaces share the same underlying gap and, per the spec author, any DNS-based mechanism Atlas could use is equally usable by a self-hosted operator with no server-side dependency.

Is this ticket only for tests?

No. This has direct functional impact on driver server-selection (SDAM) behavior — new client-configurable options and new tiered mongos selection logic are required, not just test coverage improvements.

 
Dependency to resolve during design
The proposed spec's per-host locality (DNS TXT) lookup is confirmed to only occur today as part of mongodb+srv:// seedlist discovery - there is no existing per-host TXT lookup path for hosts supplied via a plain mongodb:// connection string. Since direct/seed-list connection strings are a common pattern for self-hosted deployments, design must explicitly resolve whether this lookup can be generalized to non-SRV connections, or whether SRV adoption becomes a documented hard prerequisite for using this feature. This should not be left ambiguous.

Acceptance Criteria

• Determinism is defined and testable. The design specifies exactly how 100% of traffic is routed to preferred-region mongos instances while healthy, distinguishing this precisely from the probabilistic bias localThresholdMS already provides.
• Failover and recovery behavior is fully specified. The design describes how the driver falls through to a non-preferred region when the preferred region is unreachable, and how it resumes preferring that region once healthy again -both without application code changes, connection string changes, or restarts.
• Locality metadata is static by design. The design confirms that failover is driven by existing SDAM health/heartbeat monitoring, not by creating, updating, or removing locality metadata (e.g. DNS records) at the moment of a failover event.
• The SRV dependency is explicitly resolved. The design states plainly whether direct (non-SRV) connection strings are supported, and if not, documents SRV adoption as a required prerequisite rather than leaving it implicit.
• Atlas / self-hosted parity is addressed. The design confirms whether any mechanism required on the Atlas side (e.g. published DNS records) can be equivalently produced by a self-hosted operator with no dependency on Atlas-managed infrastructure or mongod/mongos colocation.
• Scope boundary with read preference is explicit. The design confirms this feature is limited to mongos selection in sharded topologies and does not alter read preference tagSet or replica set member selection behavior.
• Backward-compatible degradation is defined. The design specifies how a mongos host with no locality metadata is treated (fallback candidate, not an error), preserving compatibility with existing deployments that don't opt in.
• Cross-driver consistency plan exists. The design defines a single spec-level behavior and option naming convention intended for uniform implementation across all official drivers, rather than a driver-specific mechanism.
• Observability is addressed. The design specifies what, if anything, drivers surface (logs/events) when active mongos selection shifts between preferred and fallback regions.