feat: PrivateLink support (phase 1)

[nikagra]

Client Routes Configuration API (Phase 1)

Note: Depends on #java-native-protocol/45

Overview

Implements the configuration API for Client Routes feature to support PrivateLink-style cloud deployments (ScyllaDB Cloud). This is Phase 1 of the implementation - provides programmatic configuration without the full handler implementation.

Jira: DRIVER-88

Changes

New API Classes

• ClientRoutesEndpoint - Represents a single endpoint with connection ID and optional DNS address
• ClientRoutesConfig - Immutable configuration container with builder pattern

SessionBuilder Integration

• Added withClientRoutesConfig(ClientRoutesConfig) method
• Validates mutual exclusivity with custom AddressTranslator
• Automatically derives seed hosts from endpoint addresses when no contact points provided
• Supports IPv4, IPv6, and hostname formats with URI-based parsing

Configuration

• Added advanced.client-routes.table-name option (default: system.client_routes)
• Extended ProgrammaticArguments to pass configuration through session initialization
• Updated reference.conf with inline documentation

Address Parsing

• URI-based implementation (RFC 3986 compliant)
• Handles IPv4, IPv6 (bracketed), and hostnames
• Port validation (1-65535) with helpful error messages
• Default port: 9042

Supported Address Formats

// IPv4
"192.168.1.1:9042"
"192.168.1.1"         // defaults to 9042

// IPv6 (must use brackets)
"[::1]:9042"
"[2001:db8::1]:9042"
"[::1]"               // defaults to 9042

// Hostname
"my-cluster.scylladb.com:9042"
"my-cluster.scylladb.com"

Usage Example

ClientRoutesConfig config = ClientRoutesConfig.builder()
    .addEndpoint(new ClientRoutesEndpoint(
        UUID.fromString("12345678-1234-1234-1234-123456789012"),
        "my-cluster.us-east-1.aws.scylladb.com:9042"))
    .build();

CqlSession session = CqlSession.builder()
    .withClientRoutesConfig(config)
    .withLocalDatacenter("datacenter1")
    .build();

Testing

• 10 unit tests - All passing
  • ClientRoutesConfigTest (8 tests)
  • ClientRoutesSessionBuilderTest (2 tests, refactored to use Mockito)
• 8 validation tests - Address parsing edge cases
  • ClientRoutesValidationTest
• Test fixes for TypedDriverOptionTest and MapBasedDriverConfigLoaderTest

Documentation

• Updated manual/core/address_resolution/README.md with Client Routes section
• Updated reference.conf with configuration options
• Updated changelog/README.md for version 4.19.0

Validation

✅ All unit tests passing (18 tests total)
✅ No compilation errors
✅ Mutual exclusivity validation working
✅ Seed host derivation working
✅ IPv6 support working
✅ Error messages clear and helpful

What's NOT Included (Future Work)

This PR provides the configuration API only. The following are intentionally deferred to future PRs:

• ❌ Client Routes Handler implementation (DNS resolution, caching, address translation)
• ❌ Address Translator V2 API (Host ID-based translation)
• ❌ CLIENT_ROUTES_CHANGE event handling (stub exists in ControlConnection)
• ❌ Control connection event registration
• ❌ Integration tests with mock cluster

Design Decisions

1. Programmatic-only configuration - Connection IDs are sensitive; no file-based config
2. Mutual exclusivity with AddressTranslator - Prevents conflicts
3. URI-based parsing - Standards-compliant, handles IPv6 correctly, simple implementation
4. Immutable configuration - Thread-safe, prevents accidental modifications
5. Mockito for tests - Eliminated 92 lines of boilerplate code

Breaking Changes

None - this is a purely additive change.

Migration Guide

N/A - New feature, no migration needed.

Review Checklist

• API design review (immutability, builder pattern, validation)
• SessionBuilder integration review
• URI-based address parsing correctness
• Test coverage adequate
• Documentation clarity
• Error messages helpful
• No regressions in existing tests

Related

• Server PR: scylladb/scylladb#27323
• Go reference: gocql/gocql#675
• Design: Core Design Doc

[Copilot]

Pull request overview

This PR implements Phase 1 of PrivateLink support for the ScyllaDB Java Driver, introducing a configuration API for Client Routes to support AWS PrivateLink-style deployments. The implementation provides programmatic configuration for connection endpoints without the full handler implementation (deferred to future phases).

Changes:

• Introduced new API classes ClientRoutesConfig and ClientRoutesEndpoint for programmatic endpoint configuration
• Extended SessionBuilder with withClientRoutesConfig() method, including validation for mutual exclusivity with custom AddressTranslator and automatic seed host derivation
• Added configuration option advanced.client-routes.table-name with supporting infrastructure in DefaultDriverOption, TypedDriverOption, and OptionsMap
• Implemented URI-based address parsing supporting IPv4, IPv6 (bracketed), and hostname formats with port validation
• Extended ProgrammaticArguments to pass client routes configuration through session initialization
• Added comprehensive unit tests covering configuration builder, validation, and address parsing scenarios
• Updated documentation in manual/core/address_resolution/README.md explaining client routes usage and constraints

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
pom.xml	Updates native-protocol dependency to SNAPSHOT version for CLIENT_ROUTES support
core/src/main/java/com/datastax/oss/driver/api/core/config/ClientRoutesEndpoint.java	New immutable API class representing a single endpoint with connection ID and optional DNS address
core/src/main/java/com/datastax/oss/driver/api/core/config/ClientRoutesConfig.java	New immutable configuration container with builder pattern for managing client routes endpoints
core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java	Adds CLIENT_ROUTES_TABLE_NAME option for system table configuration
core/src/main/java/com/datastax/oss/driver/api/core/config/TypedDriverOption.java	Adds typed wrapper for CLIENT_ROUTES_TABLE_NAME option
core/src/main/java/com/datastax/oss/driver/api/core/config/OptionsMap.java	Sets default value "system.client_routes" for client routes table name
core/src/main/java/com/datastax/oss/driver/api/core/session/SessionBuilder.java	Integrates client routes configuration with validation, mutual exclusivity checks, and automatic seed host derivation using URI-based address parsing
core/src/main/java/com/datastax/oss/driver/api/core/session/ProgrammaticArguments.java	Extends to pass ClientRoutesConfig through session initialization
core/src/main/resources/reference.conf	Documents client-routes configuration section with table-name option
core/src/test/java/com/datastax/oss/driver/api/core/config/ClientRoutesConfigTest.java	Unit tests for ClientRoutesConfig builder functionality
core/src/test/java/com/datastax/oss/driver/api/core/session/ClientRoutesSessionBuilderTest.java	Tests for SessionBuilder integration with client routes
core/src/test/java/com/datastax/oss/driver/internal/core/session/ClientRoutesValidationTest.java	Comprehensive validation tests for address parsing edge cases
manual/core/address_resolution/README.md	Documentation for client routes feature with usage examples and constraints

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.