Add Private link support

[sylwiaszunejko]

Overview

This PR adds Private Link support to the Python driver via the system.client_routes table and CLIENT_ROUTES_CHANGE CQL protocol events. It enables the driver to dynamically translate node addresses through server-provided route mappings, which is required for Private Link.

Architecture

New classes introduced

User-facing configuration (cassandra/client_routes.py):

• ClientRouteProxy — Represents a single route endpoint configuration with a connection_id (string identifying the Private Link connection) and an optional connection_addr (used as a seed contact point).
• ClientRoutesConfig — Bundles a list of ClientRouteEntry objects. Passed to Cluster(client_routes_config=...).

Internal route storage (cassandra/client_routes.py):

• _Route — Dataclass holding a single row from system.client_routes (connection_id, host_id, address, port, tls_port, datacenter, rack). Stores only the raw table data.
• _RouteStore — Thread-safe storage for routes keyed by host_id. Uses atomic dict pointer swaps for lock-free reads and RLock-serialized writes. Includes preferred route selection logic: when multiple routes exist for the same host_id (different connection_ids), the currently active connection_id is preferred to avoid unnecessary connection migration.

Route lifecycle handler (cassandra/client_routes.py):

• _ClientRoutesHandler — Central coordinator for the client routes feature. Manages:
  • Initialization: Queries system.client_routes for all configured connection_ids after the control connection is established.
  • Event handling: Processes CLIENT_ROUTES_CHANGE events by re-querying only the affected connection_ids and host_ids, filtering to configured endpoints.
  • Control connection reconnect: Performs a full route reload (replacing all routes) to clear stale entries.
  • DNS resolution with caching: resolve_host() translates a host_id to an (ip, port) pair. DNS results are cached in a separate dict keyed by hostname (not per-route), with TTL controlled by cache_ttl_seconds. Port selection is TLS-aware (tls_port when SSL is enabled).
  • Shutdown: Marks handler as shut down to stop processing further events.

Connection-layer endpoint classes (cassandra/connection.py):

• ClientRoutesEndPointFactory — EndPointFactory implementation that creates ClientRoutesEndPoint instances from system.peers rows. Extracts only the host_id and stores a reference to the handler; no address translation or DNS resolution happens at creation time.
• ClientRoutesEndPoint — EndPoint implementation that defers all resolution to connection time. Its resolve() method delegates to _ClientRoutesHandler.resolve_host(), which looks up the route and resolves DNS. On failure, it falls back to DefaultEndPoint behavior (returning the original address/port from system.peers).

Edge cases and error handling

• No route found for a host_id: resolve_host() returns None and we fallback to to the original address/port from system.peers.
• Stale routes after reconnect: handle_control_connection_reconnect() uses _RouteStore.update() (full replace) instead of merge() to remove routes that no longer exist in system.client_routes.
• Multiple connection_ids for same host: _RouteStore._select_preferred_routes() prefers the currently active connection_id to avoid unnecessary connection migration. Falls back to the first available route when the current one disappears.
• CLIENT_ROUTES_CHANGE filtering: Events include connection_ids; the handler only processes those matching its configured endpoints, ignoring irrelevant changes.
• Mutual exclusivity: client_routes_config and endpoint_factory cannot be used together — raises ValueError at Cluster.__init__.
• DNS cache is per-hostname, not per-route: Multiple routes pointing to the same hostname share a single cache entry, avoiding redundant DNS lookups.

Pre-review checklist

• I have split my patch into logically separate commits.
• All commit messages clearly explain what they change and why.
• I added relevant tests for new features and bug fixes.
• All commits compile, pass static checks and pass test.
• PR description sums up the changes and reasons why they should be introduced.
• I have provided docstrings for the public items that I want to introduce.
• I have adjusted the documentation in ./docs/source/.
• I added appropriate Fixes: annotations to PR description.

Fixes: #692

[dkropachev]

Can you please ask AI to annotate new code

[dkropachev]

1. You need to reload add the records on control connection reconnection
2. You need to make sure that when one host_id has two records with different connection ids, it sticks to one it had before update, only when old connection id is gone it can migrate from one to another.

[sylwiaszunejko]

I pushed partial fix, I still need to address top comment #706 (review)

[sylwiaszunejko]

@dkropachev I pushed the changes, I should probably split them into smaller commit, because it got to be quite big, but I think you can review to see if the content looks right

[dkropachev]

Review of the Private Link implementation. Found several issues ranging from bugs to design improvements.

[Lorak-mmk]

Looks mostly good now!

[Lorak-mmk]

Apart from other open comments I found just one more problem.

[Lorak-mmk]

Now you don't swallow the exception at handle_control_connection_reconnect, but you do it here. Isn't that going to cause the same problem as I previously described?

[dkropachev]

@sylwiaszunejko I've implemented the requested functionality to override route addresses with proxy connection_addr when available.

The implementation:

• Adds a precalculated _proxy_addresses dictionary in the constructor for efficient O(1) lookups
• Modifies _query_routes to check for proxy address overrides when creating _Route objects
• Uses self._proxy_addresses.get(connection_id, address) to efficiently get the override address or fallback to the original

This ensures that whenever self._routes_by_host_id is updated, routes with matching connection_ids will use the configured proxy addresses instead of the addresses from system.client_routes.

All existing unit tests continue to pass. The changes are in commit 1dc487e36.

[sylwiaszunejko]

@dkropachev@Lorak-mmk
I applied Karol's suggestions about querying for routes in _try_connect, to do that I changed the API to have connection and timeout as arguments instead of CC.
Also I Dmitry, I had to change a little bit some of your recent changes as integrations tests were failing, please take a look

[Lorak-mmk]

A few comments, mostly about integration of new system with CC

[dkropachev]

By defautl it should be disabled, but we should have an option to enabled it through ClientRouteConfig