4.x: PrivateLink Support Phase 3: Query Implementation, DNS Resolution & Unit Tests 🔌

[nikagra]

4.x: PrivateLink Support Phase 3: Query Implementation, DNS Resolution & Tests 🔌

Previous phases:

• 4.x: PrivateLink Support Phase 1: Configuration ⚙️ #803
• 4.x: PrivateLink Support Phase 2: Core Infrastructure 🏗️ #804

Overview

Completes the runtime implementation of PrivateLink/client-routes support for ScyllaDB Cloud. The
driver can now query system.client_routes at startup and on control-connection reconnect, resolve
node hostnames to InetSocketAddress via a TTL-aware caching DNS resolver, and dynamically
translate addresses used for every CQL connection.

Server-side feature requires scylladb/scylladb#27323.

---

Changes

Event Negotiation Fix — ProtocolInitHandler (SCYLLADB-850)

• Introduced a mutable registerEventTypes list (copy of options.eventTypes) so the REGISTER
  step can be retried with a narrowed event set without mutating the original channel options.
• When the REGISTER step receives a PROTOCOL_ERROR whose message contains
  CLIENT_ROUTES_CHANGE, the driver logs a warning, removes that event type, and retries REGISTER
  with the remaining types (SCHEMA_CHANGE, STATUS_CHANGE, TOPOLOGY_CHANGE).
• If no event types remain after stripping, the handler calls setConnectSuccess() directly,
  skipping REGISTER altogether.
• This makes the driver backward-compatible with ScyllaDB Enterprise < 2026.1: client-routes table
  queries may still work on those versions, but live push-updates via the event are disabled.

DNS Resolution — CachingDnsResolver (new)

• TTL-based in-memory cache backed by ConcurrentHashMap<String, CacheEntry> with per-hostname
  Semaphore(1) to prevent concurrent re-resolution storms.
• Fast-path unlocked read; double-checked locking only when the entry is absent or stale.
• Last-known-good fallback: on UnknownHostException, the previous successful resolution is
  returned and a warning is logged.
• clearCache() preserves last-known-good entries so a full session re-init survives transient DNS
  failures.

Client Routes Query — ClientRoutesHandler

• queryAndResolveRoutes() implemented: executes
  SELECT connection_id, host_id, address, port, tls_port FROM %s WHERE connection_id IN :connectionIds ALLOW FILTERING
  via AdminRequestHandler.
• CachingDnsResolver wired in, replacing the Phase 2 no-op stub.
• Route map atomically swapped via AtomicReference.set() so in-flight translations see a
  consistent snapshot.

Session Lifecycle — DefaultSession

• initClientRoutes() inserted between topologyMonitor.init() and
  metadataManager.refreshNodes() in the startup chain.
• Failure is non-fatal: if the client-routes query fails at startup, the session still opens and
  falls back to direct addressing.

Reconnect Integration — ControlConnection

• On a successful reconnect, clientRoutesHandler.refresh() is awaited before refreshNodes(),
  so translated addresses are current before nodes are re-evaluated.

---

Tests

Unit Tests — 22 new tests across 3 suites

Suite	#	Coverage
CachingDnsResolverTest	7	Cache hit/miss, TTL expiry, concurrency, last-known-good fallback, clearCache()
ClientRoutesHandlerTest	8	Query construction, route-map population, translate with/without SSL, refresh no-op when disabled
ClientRoutesAddressTranslatorTest	7	Address translation pipeline, null pass-through, SSL port selection

Integration Tests — 6 new tests across 2 suites

Suite	Requirement	#	Coverage
ClientRoutesIT	ScyllaDB Enterprise ≥ 2026.1	5	Routes loaded on init; refresh() picks up new rows; session opens with empty table; TLS port selection; auto-refresh on control-connection reconnect
ClientRoutesUnsupportedVersionIT	ScyllaDB Enterprise < 2026.1	1	Session opens and handler returns null when system.client_routes is absent (graceful degradation)

Both integration test suites are @Category(IsolatedTests.class) and @ScyllaOnly. Positive tests
use a user-space mirror table (test_client_routes.client_routes) to avoid requiring privileged
write access to system.

Additional notes

This PR also uses workaround for SCYLLADB-850: older ScyllaDB Enterprise versions (< 2026.1) reject the CLIENT_ROUTES_CHANGE REGISTER event with a PROTOCOL_ERROR, which previously caused connection initialisation to fail. The driver now gracefully handles this by stripping the unsupported event and retrying REGISTER with the remaining types, so sessions succeed on any server version.

---

Related to DRIVER-86, DRIVER-88, SCYLLADB-850

[Copilot]

Pull request overview

This PR completes Phase 3 of PrivateLink support for the Java driver, implementing the runtime components required for ScyllaDB Cloud deployments. Building on Phase 2's infrastructure (#804), it adds DNS resolution, query execution, and complete lifecycle integration for the client routes feature.

Changes:

• Implements TTL-based caching DNS resolver with last-known-good fallback and concurrency control
• Adds query execution for system.client_routes table with hostname resolution and route map management
• Integrates client routes initialization into session startup and control-connection reconnect lifecycle
• Implements backward-compatible event negotiation to handle older ScyllaDB versions that don't support CLIENT_ROUTES_CHANGE events

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
pom.xml	Upgrades native protocol to 1.5.2.2 to support CLIENT_ROUTES_CHANGE event
manual/core/address_resolution/README.md	Documents client routes configuration and usage with examples
core/.../util/AddressParser.java	New utility for parsing contact point addresses with IPv4/IPv6/hostname support
core/.../clientroutes/DnsResolver.java	Interface defining DNS resolution with caching requirements
core/.../clientroutes/CachingDnsResolver.java	TTL-based DNS caching implementation with semaphore-based concurrency control
core/.../clientroutes/ClientRouteInfo.java	Data structure representing raw client_routes table rows
core/.../clientroutes/ResolvedClientRoute.java	Resolved route with DNS resolution capability
core/.../clientroutes/ClientRoutesHandler.java	Main coordinator implementing query execution and route management
core/.../clientroutes/ClientRoutesAddressTranslator.java	AddressTranslator implementation delegating to handler
core/.../session/DefaultSession.java	Integrates client routes initialization into session startup
core/.../metadata/DefaultTopologyMonitor.java	Passes node metadata (hostId, datacenter, rack) to address translator
core/.../control/ControlConnection.java	Adds CLIENT_ROUTES_CHANGE event handling and reconnect integration
core/.../context/DefaultDriverContext.java	Wires client routes handler into driver context
core/.../context/InternalDriverContext.java	Adds getClientRoutesHandler() method
core/.../channel/ProtocolInitHandler.java	Implements backward-compatible event negotiation for CLIENT_ROUTES_CHANGE
core/.../session/SessionBuilder.java	Adds withClientRoutesConfig() with mutual exclusivity validation
core/.../session/ProgrammaticArguments.java	Stores client routes config in programmatic arguments
core/.../config/ClientRoutesConfig.java	Configuration class for client routes with builder
core/.../config/ClientRoutesEndpoint.java	Represents a single client routes endpoint
core/.../addresstranslation/AddressTranslator.java	Adds overloaded translate() method accepting node metadata
core/.../config/DefaultDriverOption.java	Minor formatting cleanup (blank line removal)
core/src/main/resources/reference.conf	Minor formatting cleanup (blank line removal)
core/src/test/.../util/AddressParserTest.java	Comprehensive unit tests for address parsing
core/src/test/.../clientroutes/CachingDnsResolverTest.java	Unit tests for DNS resolver cache behavior
core/src/test/.../clientroutes/ClientRoutesHandlerTest.java	Unit tests for handler translate() method
core/src/test/.../clientroutes/ClientRoutesAddressTranslatorTest.java	Unit tests for address translator delegation
core/src/test/.../session/ClientRoutesSessionBuilderTest.java	Unit tests for session builder configuration
core/src/test/.../config/ClientRoutesConfigTest.java	Unit tests for configuration validation
core/src/test/.../metadata/DefaultTopologyMonitorTest.java	Updates test verification counts for additional getString() calls