client routes: add exclusive-proxy config to control fallback behavior

[nikagra]

Summary

• Adds advanced.client-routes.exclusive-proxy (boolean, default false) to control whether the driver falls back to a node's broadcast address when no route entry exists in system.client_routes
• When false (default): nodes without a route entry are reached directly via their broadcast address — backward-compatible, supports mixed proxy/direct topologies
• When true: any node without a route is treated as unreachable; resolve() throws IllegalStateException with a WARN log, the node stays DOWN, and the reconnection loop retries until CLIENT_ROUTES_CHANGE populates the route

Motivation

Two requirements needed to coexist:

1. Mixed proxy/direct topologies (original design): some nodes are behind the private endpoint, others are not — the driver connects directly to unrouted nodes. The default exclusive-proxy = false preserves this behavior.

2. Strict proxy enforcement (new): when a new node is added there is a race window before its system.client_routes entry is published. With exclusive-proxy = true the driver refuses to bypass the proxy during this window, matching the behavior of the Rust driver fix (failing address translation on missing entries). The node goes DOWN and reconnects once the route is available.

Changes

• DefaultDriverOption: new CLIENT_ROUTES_EXCLUSIVE_PROXY enum constant
• TypedDriverOption: new typed Boolean constant
• reference.conf: advanced.client-routes.exclusive-proxy = false with documentation
• ClientRoutesEndPoint: restored fallbackEndPoint field; resolve() uses the fallback when exclusive-proxy = false, throws IllegalStateException + WARN when exclusive-proxy = true
• ClientRoutesTopologyMonitor: reads config flag in constructor; passes fallback endpoint (null when exclusive-proxy is true) and flag to ClientRoutesEndPoint
• Tests: constructor calls updated; separate test cases for exclusive and non-exclusive modes; createHandlerWithExclusiveProxy() helper in the topology monitor test

Not in this PR

• Graceful migration (soft-drop of existing direct connections when a route is added for a node) — tracked as a follow-up

[dkropachev]

@nikagra , I would prefere to have an option to enable it and handle case when host switches from direct connection to client routes, you can make host connection pool either softly drop all the connections that used to directly, check if it won't blow the PR.

[Copilot]

Pull request overview

Adds an advanced.client-routes.exclusive-proxy configuration flag to control whether the driver may fall back to a node’s broadcast address when no entry exists in system.client_routes.

Changes:

• Introduces CLIENT_ROUTES_EXCLUSIVE_PROXY as a new built-in driver option (typed + defaulted).
• Updates client-routes endpoint resolution to either fall back (default) or throw when a route is missing (exclusive mode).
• Updates reference configuration documentation and expands tests to cover both exclusive/non-exclusive behaviors.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
core/src/main/java/com/datastax/oss/driver/internal/core/metadata/ClientRoutesTopologyMonitor.java	Reads the new flag and passes fallback endpoint as null in exclusive mode; adjusts endpoint construction behavior.
core/src/main/java/com/datastax/oss/driver/internal/core/metadata/ClientRoutesEndPoint.java	Adds exclusive-proxy behavior in resolve() (fallback vs WARN+throw) and updates constructor contract.
core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java	Adds CLIENT_ROUTES_EXCLUSIVE_PROXY option path.
core/src/main/java/com/datastax/oss/driver/api/core/config/TypedDriverOption.java	Adds typed Boolean option constant for exclusive-proxy.
core/src/main/java/com/datastax/oss/driver/api/core/config/OptionsMap.java	Registers default value (false) for the new typed option.
core/src/main/resources/reference.conf	Documents advanced.client-routes.exclusive-proxy with default false.
core/src/test/java/com/datastax/oss/driver/internal/core/metadata/ClientRoutesTopologyMonitorTest.java	Adds/updates tests for exclusive vs non-exclusive fallback behavior and host_id-null handling.
core/src/test/java/com/datastax/oss/driver/internal/core/metadata/ClientRoutesEndPointTest.java	Updates constructor calls and adds tests for exclusive mode throwing vs fallback mode.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.