Client routes enable the driver to discover and connect to nodes through a load balancer (such + * as AWS PrivateLink) by reading endpoint mappings from the {@code system.client_routes} table. + * Each endpoint is identified by a connection ID and maps to specific node addresses. + * + *
This configuration is mutually exclusive with a user-provided {@link + * com.datastax.oss.driver.api.core.addresstranslation.AddressTranslator}. If client routes are + * configured, the driver will use its internal client routes handler for address translation. + * + *
Example usage: + * + *
{@code
+ * ClientRoutesConfig config = ClientRoutesConfig.builder()
+ * .addEndpoint(new ClientRoutesEndpoint(
+ * UUID.fromString("12345678-1234-1234-1234-123456789012"),
+ * "my-privatelink.us-east-1.aws.scylladb.com:9042"))
+ * .build();
+ *
+ * CqlSession session = CqlSession.builder()
+ * .withClientRoutesConfig(config)
+ * .build();
+ * }
+ *
+ * @see SessionBuilder#withClientRoutesConfig(ClientRoutesConfig)
+ * @see ClientRoutesEndpoint
+ */
+@Immutable
+public class ClientRoutesConfig {
+
+ private final ListThis is primarily useful for testing. If not set, the driver will use the default table + * name from the configuration ({@code system.client_routes}). + * + * @param tableName the table name to use. + * @return this builder. + */ + @NonNull + public Builder withTableName(@Nullable String tableName) { + this.tableName = tableName; + return this; + } + + /** + * Builds the {@link ClientRoutesConfig} with the configured endpoints and table name. + * + * @return the new configuration instance. + * @throws IllegalArgumentException if no endpoints have been added. + */ + @NonNull + public ClientRoutesConfig build() { + return new ClientRoutesConfig(endpoints, tableName); + } + } +} diff --git a/core/src/main/java/com/datastax/oss/driver/api/core/config/ClientRoutesEndpoint.java b/core/src/main/java/com/datastax/oss/driver/api/core/config/ClientRoutesEndpoint.java new file mode 100644 index 00000000000..516d6fd9268 --- /dev/null +++ b/core/src/main/java/com/datastax/oss/driver/api/core/config/ClientRoutesEndpoint.java @@ -0,0 +1,103 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package com.datastax.oss.driver.api.core.config; + +import edu.umd.cs.findbugs.annotations.NonNull; +import edu.umd.cs.findbugs.annotations.Nullable; +import java.util.Objects; +import java.util.UUID; +import net.jcip.annotations.Immutable; + +/** + * Represents a client routes endpoint for PrivateLink-style deployments. + * + *
Each endpoint corresponds to a connection ID in the {@code system.client_routes} table, with + * an optional connection address that can be used as a seed host for initial connection. + */ +@Immutable +public class ClientRoutesEndpoint { + + private final UUID connectionId; + private final String connectionAddr; + + /** + * Creates a new endpoint with the given connection ID and no connection address. + * + * @param connectionId the connection ID (must not be null). + */ + public ClientRoutesEndpoint(@NonNull UUID connectionId) { + this(connectionId, null); + } + + /** + * Creates a new endpoint with the given connection ID and connection address. + * + * @param connectionId the connection ID (must not be null). + * @param connectionAddr the connection address to use as a seed host (may be null). + */ + public ClientRoutesEndpoint(@NonNull UUID connectionId, @Nullable String connectionAddr) { + this.connectionId = Objects.requireNonNull(connectionId, "connectionId must not be null"); + this.connectionAddr = connectionAddr; + } + + /** Returns the connection ID for this endpoint. */ + @NonNull + public UUID getConnectionId() { + return connectionId; + } + + /** + * Returns the connection address for this endpoint, or null if not specified. + * + *
When provided and no explicit contact points are given to the session builder, this address + * will be used as a seed host for the initial connection. + */ + @Nullable + public String getConnectionAddr() { + return connectionAddr; + } + + @Override + public boolean equals(Object o) { + if (this == o) { + return true; + } + if (!(o instanceof ClientRoutesEndpoint)) { + return false; + } + ClientRoutesEndpoint that = (ClientRoutesEndpoint) o; + return connectionId.equals(that.connectionId) + && Objects.equals(connectionAddr, that.connectionAddr); + } + + @Override + public int hashCode() { + return Objects.hash(connectionId, connectionAddr); + } + + @Override + public String toString() { + return "ClientRoutesEndpoint{" + + "connectionId=" + + connectionId + + ", connectionAddr='" + + connectionAddr + + '\'' + + '}'; + } +} diff --git a/core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java b/core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java index 9e0119903df..68209b1f240 100644 --- a/core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java +++ b/core/src/main/java/com/datastax/oss/driver/api/core/config/DefaultDriverOption.java @@ -449,6 +449,17 @@ public enum DefaultDriverOption implements DriverOption { */ ADDRESS_TRANSLATOR_CLASS("advanced.address-translator.class"), + /** + * The name of the system table to query for client routes information. + * + *
This is used when client routes are configured programmatically via {@link + * com.datastax.oss.driver.api.core.session.SessionBuilder#withClientRoutesConfig}. The default + * value is {@code system.client_routes}. + * + *
Value-type: {@link String}
+ */
+ CLIENT_ROUTES_TABLE_NAME("advanced.client-routes.table-name"),
+
/**
* The native protocol version to use.
*
diff --git a/core/src/main/java/com/datastax/oss/driver/api/core/config/OptionsMap.java b/core/src/main/java/com/datastax/oss/driver/api/core/config/OptionsMap.java
index 28559ea8556..3a999146c9b 100644
--- a/core/src/main/java/com/datastax/oss/driver/api/core/config/OptionsMap.java
+++ b/core/src/main/java/com/datastax/oss/driver/api/core/config/OptionsMap.java
@@ -396,6 +396,7 @@ protected static void fillWithDriverDefaults(OptionsMap map) {
map.put(
TypedDriverOption.LOAD_BALANCING_DEFAULT_LWT_REQUEST_ROUTING_METHOD,
"PRESERVE_REPLICA_ORDER");
+ map.put(TypedDriverOption.CLIENT_ROUTES_TABLE_NAME, "system.client_routes");
}
@Immutable
diff --git a/core/src/main/java/com/datastax/oss/driver/api/core/config/TypedDriverOption.java b/core/src/main/java/com/datastax/oss/driver/api/core/config/TypedDriverOption.java
index 818468ee9d5..7ea10faf841 100644
--- a/core/src/main/java/com/datastax/oss/driver/api/core/config/TypedDriverOption.java
+++ b/core/src/main/java/com/datastax/oss/driver/api/core/config/TypedDriverOption.java
@@ -939,6 +939,9 @@ public String toString() {
DefaultDriverOption.LOAD_BALANCING_DEFAULT_LWT_REQUEST_ROUTING_METHOD,
GenericType.STRING);
+ public static final TypedDriverOption Client routes enable the driver to discover and connect to nodes through a load balancer
+ * (such as AWS PrivateLink) by reading endpoint mappings from the {@code system.client_routes}
+ * table. Each endpoint is identified by a connection ID and maps to specific node addresses.
+ *
+ * This configuration is mutually exclusive with a user-provided {@link AddressTranslator}. If
+ * both are specified, an error will be thrown during session initialization. If you need custom
+ * address translation behavior with client routes, the driver's internal client routes handler
+ * will be used.
+ *
+ * Example usage:
+ *
+ * Accepted formats:
+ * {@code
+ * ClientRoutesConfig config = ClientRoutesConfig.builder()
+ * .addEndpoint(new ClientRoutesEndpoint(
+ * UUID.fromString("12345678-1234-1234-1234-123456789012"),
+ * "my-privatelink.us-east-1.aws.scylladb.com:9042"))
+ * .build();
+ *
+ * CqlSession session = CqlSession.builder()
+ * .withClientRoutesConfig(config)
+ * .build();
+ * }
+ *
+ * @param clientRoutesConfig the client routes configuration to use, or null to disable client
+ * routes.
+ * @see ClientRoutesConfig
+ */
+ @NonNull
+ public SelfT withClientRoutesConfig(@Nullable ClientRoutesConfig clientRoutesConfig) {
+ this.clientRoutesConfig = clientRoutesConfig;
+ this.programmaticArgumentsBuilder.withClientRoutesConfig(clientRoutesConfig);
+ return self;
+ }
+
/**
* A unique identifier for the created session.
*
@@ -898,6 +939,44 @@ protected final CompletionStage
+ *
+ *
+ * @param address the address string to parse
+ * @param connectionId the connection ID for error messages
+ * @return an InetSocketAddress
+ * @throws IllegalArgumentException if the address format is invalid
+ */
+ private static InetSocketAddress parseContactPoint(String address, UUID connectionId) {
+ try {
+ // Add scheme to make it a valid URI for parsing
+ // URI class handles IPv6 brackets, hostname, and port correctly
+ String uriString = address.contains("://") ? address : "cql://" + address;
+ java.net.URI uri = new java.net.URI(uriString);
+
+ String host = uri.getHost();
+ int port = uri.getPort();
+
+ // Validate we got a host
+ if (host == null || host.isEmpty()) {
+ throw new IllegalArgumentException(
+ String.format(
+ "Invalid address format '%s' (connection ID: %s). "
+ + "Expected format: 'host:port' or '[ipv6]:port'",
+ address, connectionId));
+ }
+
+ // Use default port if not specified
+ if (port == -1) {
+ port = 9042;
+ }
+
+ // Validate port range
+ if (port < 1 || port > 65535) {
+ throw new IllegalArgumentException(
+ String.format(
+ "Invalid port %d in address '%s' (connection ID: %s). "
+ + "Port must be between 1 and 65535.",
+ port, address, connectionId));
+ }
+
+ return new InetSocketAddress(host, port);
+
+ } catch (java.net.URISyntaxException e) {
+ throw new IllegalArgumentException(
+ String.format(
+ "Invalid address format '%s' (connection ID: %s). "
+ + "Expected format: 'host:port' or '[ipv6]:port'. %s",
+ address, connectionId, e.getMessage()),
+ e);
+ }
+ }
+
/**
* Returns URL based on the configUrl setting. If the configUrl has no protocol provided, the
* method will fallback to file:// protocol and return URL that has file protocol specified.
diff --git a/core/src/main/resources/reference.conf b/core/src/main/resources/reference.conf
index 40d56d67341..f847dc8d28c 100644
--- a/core/src/main/resources/reference.conf
+++ b/core/src/main/resources/reference.conf
@@ -1110,6 +1110,29 @@ datastax-java-driver {
# advertised-hostname = mycustomhostname
}
+ # Client routes configuration for PrivateLink-style deployments.
+ #
+ # Client routes enable the driver to discover and connect to nodes through a load balancer
+ # (such as AWS PrivateLink) by reading endpoint mappings from the system.client_routes table.
+ # Each endpoint is identified by a connection ID and maps to specific node addresses.
+ #
+ # Note: Client routes endpoints are configured programmatically via
+ # SessionBuilder.withClientRoutesConfig(). This configuration section only provides the
+ # system table name option.
+ #
+ # Client routes are mutually exclusive with a custom AddressTranslator. If client routes are
+ # configured programmatically, the address-translator.class option must be set to
+ # PassThroughAddressTranslator (the default), otherwise session initialization will fail.
+ #
+ # Required: no (programmatic configuration only)
+ # Modifiable at runtime: no
+ # Overridable in a profile: no
+ advanced.client-routes {
+ # The name of the system table to query for client routes information.
+ # This is typically only changed for testing purposes.
+ table-name = "system.client_routes"
+ }
+
# Whether to resolve the addresses passed to `basic.contact-points`.
#
# If this is true, addresses are created with `InetSocketAddress(String, int)`: the host name will
diff --git a/core/src/test/java/com/datastax/oss/driver/api/core/config/ClientRoutesConfigTest.java b/core/src/test/java/com/datastax/oss/driver/api/core/config/ClientRoutesConfigTest.java
new file mode 100644
index 00000000000..71bc64666b9
--- /dev/null
+++ b/core/src/test/java/com/datastax/oss/driver/api/core/config/ClientRoutesConfigTest.java
@@ -0,0 +1,123 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.datastax.oss.driver.api.core.config;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.util.UUID;
+import org.junit.Test;
+
+public class ClientRoutesConfigTest {
+
+ @Test
+ public void should_build_config_with_single_endpoint() {
+ UUID connectionId = UUID.randomUUID();
+ String connectionAddr = "my-privatelink.us-east-1.aws.scylladb.com:9042";
+
+ ClientRoutesConfig config =
+ ClientRoutesConfig.builder()
+ .addEndpoint(new ClientRoutesEndpoint(connectionId, connectionAddr))
+ .build();
+
+ assertThat(config.getEndpoints()).hasSize(1);
+ assertThat(config.getEndpoints().get(0).getConnectionId()).isEqualTo(connectionId);
+ assertThat(config.getEndpoints().get(0).getConnectionAddr()).isEqualTo(connectionAddr);
+ assertThat(config.getTableName()).isNull();
+ }
+
+ @Test
+ public void should_build_config_with_multiple_endpoints() {
+ UUID connectionId1 = UUID.randomUUID();
+ UUID connectionId2 = UUID.randomUUID();
+
+ ClientRoutesConfig config =
+ ClientRoutesConfig.builder()
+ .addEndpoint(new ClientRoutesEndpoint(connectionId1, "host1:9042"))
+ .addEndpoint(new ClientRoutesEndpoint(connectionId2, "host2:9042"))
+ .build();
+
+ assertThat(config.getEndpoints()).hasSize(2);
+ assertThat(config.getEndpoints().get(0).getConnectionId()).isEqualTo(connectionId1);
+ assertThat(config.getEndpoints().get(1).getConnectionId()).isEqualTo(connectionId2);
+ }
+
+ @Test
+ public void should_build_config_with_custom_table_name() {
+ ClientRoutesConfig config =
+ ClientRoutesConfig.builder()
+ .addEndpoint(new ClientRoutesEndpoint(UUID.randomUUID()))
+ .withTableName("custom.client_routes_test")
+ .build();
+
+ assertThat(config.getTableName()).isEqualTo("custom.client_routes_test");
+ }
+
+ @Test
+ public void should_fail_when_no_endpoints_provided() {
+ assertThatThrownBy(() -> ClientRoutesConfig.builder().build())
+ .isInstanceOf(IllegalArgumentException.class)
+ .hasMessageContaining("At least one endpoint must be specified");
+ }
+
+ @Test
+ public void should_create_endpoint_without_connection_address() {
+ UUID connectionId = UUID.randomUUID();
+ ClientRoutesEndpoint endpoint = new ClientRoutesEndpoint(connectionId);
+
+ assertThat(endpoint.getConnectionId()).isEqualTo(connectionId);
+ assertThat(endpoint.getConnectionAddr()).isNull();
+ }
+
+ @Test
+ public void should_create_endpoint_with_connection_address() {
+ UUID connectionId = UUID.randomUUID();
+ String connectionAddr = "host:9042";
+ ClientRoutesEndpoint endpoint = new ClientRoutesEndpoint(connectionId, connectionAddr);
+
+ assertThat(endpoint.getConnectionId()).isEqualTo(connectionId);
+ assertThat(endpoint.getConnectionAddr()).isEqualTo(connectionAddr);
+ }
+
+ @Test
+ public void should_fail_when_connection_id_is_null() {
+ assertThatThrownBy(() -> new ClientRoutesEndpoint(null))
+ .isInstanceOf(NullPointerException.class)
+ .hasMessageContaining("connectionId must not be null");
+ }
+
+ @Test
+ public void should_replace_endpoints_with_withEndpoints() {
+ UUID connectionId1 = UUID.randomUUID();
+ UUID connectionId2 = UUID.randomUUID();
+ UUID connectionId3 = UUID.randomUUID();
+
+ ClientRoutesConfig config =
+ ClientRoutesConfig.builder()
+ .addEndpoint(new ClientRoutesEndpoint(connectionId1))
+ .withEndpoints(
+ java.util.Arrays.asList(
+ new ClientRoutesEndpoint(connectionId2),
+ new ClientRoutesEndpoint(connectionId3)))
+ .build();
+
+ assertThat(config.getEndpoints()).hasSize(2);
+ assertThat(config.getEndpoints().get(0).getConnectionId()).isEqualTo(connectionId2);
+ assertThat(config.getEndpoints().get(1).getConnectionId()).isEqualTo(connectionId3);
+ }
+}
diff --git a/core/src/test/java/com/datastax/oss/driver/api/core/session/ClientRoutesSessionBuilderTest.java b/core/src/test/java/com/datastax/oss/driver/api/core/session/ClientRoutesSessionBuilderTest.java
new file mode 100644
index 00000000000..f2d48eeb2ee
--- /dev/null
+++ b/core/src/test/java/com/datastax/oss/driver/api/core/session/ClientRoutesSessionBuilderTest.java
@@ -0,0 +1,85 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.datastax.oss.driver.api.core.session;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.mock;
+
+import com.datastax.oss.driver.api.core.CqlSession;
+import com.datastax.oss.driver.api.core.config.ClientRoutesConfig;
+import com.datastax.oss.driver.api.core.config.ClientRoutesEndpoint;
+import java.util.UUID;
+import org.junit.Test;
+
+public class ClientRoutesSessionBuilderTest {
+
+ @Test
+ public void should_set_client_routes_config_programmatically() {
+ UUID connectionId = UUID.randomUUID();
+ ClientRoutesConfig config =
+ ClientRoutesConfig.builder()
+ .addEndpoint(new ClientRoutesEndpoint(connectionId, "host:9042"))
+ .build();
+
+ TestSessionBuilder builder = new TestSessionBuilder();
+ builder.withClientRoutesConfig(config);
+
+ assertThat(builder.clientRoutesConfig).isEqualTo(config);
+ assertThat(builder.programmaticArgumentsBuilder.build().getClientRoutesConfig())
+ .isEqualTo(config);
+ }
+
+ @Test
+ public void should_allow_null_client_routes_config() {
+ TestSessionBuilder builder = new TestSessionBuilder();
+ builder.withClientRoutesConfig(null);
+
+ assertThat(builder.clientRoutesConfig).isNull();
+ assertThat(builder.programmaticArgumentsBuilder.build().getClientRoutesConfig()).isNull();
+ }
+
+ @Test
+ public void should_validate_connection_address_format() {
+ // Valid formats should be accepted (tested in integration/functional tests)
+ // Here we test that invalid formats produce helpful error messages
+
+ UUID connectionId = UUID.randomUUID();
+
+ // Invalid port: not a number
+ ClientRoutesConfig configInvalidPort = ClientRoutesConfig.builder()
+ .addEndpoint(new ClientRoutesEndpoint(connectionId, "host:abc"))
+ .build();
+
+ // Note: Actual validation happens in SessionBuilder.buildDefaultSessionAsync()
+ // which is called during session.build(). Since we can't easily test that here
+ // without creating a full session (which requires infrastructure), we document
+ // the expected behavior:
+ // - "host:abc" should throw IllegalArgumentException: "Invalid port number 'abc'..."
+ // - "host:99999" should throw IllegalArgumentException: "Port must be between 1 and 65535"
+ // These are tested in ClientRoutesValidationTest.
+ }
+
+ /** Test subclass to access protected fields. */
+ private static class TestSessionBuilder extends SessionBuilder