4.x: PrivateLink Support Phase 2: Core Infrastructure 🏗️

[nikagra]

4.x: PrivateLink Support Phase 2: Core Infrastructure 🏗️

Overview

Note: Depends on #803. ❗

Implements foundational infrastructure for Client Routes support (AWS PrivateLink),
enabling dynamic address translation based on Host ID instead of IP addresses.

This is Phase 2 - establishes complete API surface and integration points.
Actual query implementation and lifecycle hooks will follow in Phase 3.

Changes

Protocol Layer:

• Conditional CLIENT_ROUTES_CHANGE event registration in ControlConnection
• Event handler with async refresh trigger

API Surface:

• AddressTranslator V2: translate(address, hostId, datacenter, rack)
• ClientRoutesConfig: User-facing configuration with DNS cache tuning
• ClientRoutesEndpoint: Per-connection endpoint configuration

Infrastructure:

• ClientRoutesHandler: Main coordinator (stub implementation)
• ClientRoutesAddressTranslator: Translator wrapper
• ClientRouteInfo, ResolvedClientRoute: Data structures

Integration:

• DefaultDriverContext: Lazy handler initialization
• DefaultSession: Handler lifecycle management
• DefaultTopologyMonitor: Host metadata passing
• SessionBuilder: Configuration and validation

Tests:

• ClientRoutesConfigTest: Config validation (10 tests)
• ClientRoutesSessionBuilderTest: Builder integration (6 tests)

Deferred to Phase 3 ⏳

• Actual CQL query to system.client_routes
• DNS resolution implementation
• Handler.init() lifecycle integration
• Comprehensive unit and integration tests
• User documentation

---

Related to DRIVER-86, DRIVER-88

[Copilot]

Pull request overview

This PR implements Phase 2 of PrivateLink support for the Java driver, building upon the configuration API introduced in PR #803. It establishes the complete infrastructure and integration points needed for dynamic address translation based on Host IDs, enabling AWS PrivateLink-style cloud deployments where nodes are accessed through private DNS endpoints.

Changes:

• Adds AddressTranslator V2 API with new translate(address, hostId, datacenter, rack) method for metadata-aware address translation
• Implements core infrastructure: ClientRoutesHandler (stub coordinator), ClientRoutesAddressTranslator (wrapper), and supporting data structures
• Integrates client routes throughout the driver lifecycle: DefaultDriverContext, DefaultSession, DefaultTopologyMonitor, ControlConnection with CLIENT_ROUTES_CHANGE event handling
• Adds AddressParser utility for robust IPv4/IPv6/hostname parsing with comprehensive test coverage
• Updates native-protocol dependency from 1.5.2.1 to 1.5.2.2 for CLIENT_ROUTES_CHANGE event support

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pom.xml	Bumps native-protocol version to 1.5.2.2 for CLIENT_ROUTES_CHANGE event support
manual/core/address_resolution/README.md	Adds Client Routes documentation section with usage examples and configuration details
core/src/main/resources/reference.conf	Documents advanced.client-routes.table-name configuration option
core/src/main/java/com/datastax/oss/driver/api/core/addresstranslation/AddressTranslator.java	Adds V2 translate() method with hostId/datacenter/rack parameters (backward compatible default)
core/src/main/java/com/datastax/oss/driver/api/core/config/ClientRoutesConfig.java	Immutable configuration class with builder pattern, DNS cache settings
core/src/main/java/com/datastax/oss/driver/api/core/config/ClientRoutesEndpoint.java	Represents a single endpoint with connection ID and optional address
core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java	Adds CLIENT_ROUTES_TABLE_NAME option
core/src/main/java/com/datastax/oss/driver/api/core/config/TypedDriverOption.java	Adds typed constant for CLIENT_ROUTES_TABLE_NAME
core/src/main/java/com/datastax/oss/driver/api/core/config/OptionsMap.java	Sets default value for client-routes.table-name
core/src/main/java/com/datastax/oss/driver/api/core/session/SessionBuilder.java	Adds withClientRoutesConfig() method with mutual exclusivity validation
core/src/main/java/com/datastax/oss/driver/api/core/session/ProgrammaticArguments.java	Extends to carry ClientRoutesConfig through session initialization
core/src/main/java/com/datastax/oss/driver/internal/core/util/AddressParser.java	URI-based parser for IPv4/IPv6/hostname addresses with port validation
core/src/main/java/com/datastax/oss/driver/internal/core/clientroutes/ClientRoutesHandler.java	Main coordinator with stub implementation, DNS caching, and lifecycle methods
core/src/main/java/com/datastax/oss/driver/internal/core/clientroutes/ClientRoutesAddressTranslator.java	Delegates to ClientRoutesHandler for Host ID-based translation
core/src/main/java/com/datastax/oss/driver/internal/core/clientroutes/ClientRouteInfo.java	Represents raw row from system.client_routes table
core/src/main/java/com/datastax/oss/driver/internal/core/clientroutes/ResolvedClientRoute.java	Represents DNS-resolved route with SSL port support
core/src/main/java/com/datastax/oss/driver/internal/core/context/InternalDriverContext.java	Adds getClientRoutesHandler() method
core/src/main/java/com/datastax/oss/driver/internal/core/context/DefaultDriverContext.java	Implements lazy ClientRoutesHandler initialization and ClientRoutesAddressTranslator construction
core/src/main/java/com/datastax/oss/driver/internal/core/session/DefaultSession.java	Adds ClientRoutesHandler to lifecycle cleanup
core/src/main/java/com/datastax/oss/driver/internal/core/metadata/DefaultTopologyMonitor.java	Passes hostId/datacenter/rack to AddressTranslator.translate()
core/src/main/java/com/datastax/oss/driver/internal/core/control/ControlConnection.java	Registers CLIENT_ROUTES_CHANGE event and triggers async refresh
core/src/test/java/com/datastax/oss/driver/internal/core/util/AddressParserTest.java	Comprehensive tests for address parsing (11 test methods)
core/src/test/java/com/datastax/oss/driver/api/core/config/ClientRoutesConfigTest.java	Tests for configuration builder and validation (10 test methods)
core/src/test/java/com/datastax/oss/driver/api/core/session/ClientRoutesSessionBuilderTest.java	Tests for SessionBuilder integration (2 test methods)