Rename ClientRouteEntry to ClientRoutesContactPoint

Rename class and all related fields: deployments -> contact_points,
endpoints -> contact_points, _initial_endpoints -> _initial_contact_points,
_connection_ids -> _initial_contact_points. Update logs, error messages,
docstrings, and tests to match.

Author: dkropachev

cassandra/client_routes.py

@@ -50,7 +50,7 @@ class ClientRoutesChangeType(enum.Enum):
     UPDATE_NODES = "UPDATE_NODES"
 
 
-class PrivateLinkDeployment:
+class ClientRoutesContactPoint:
 
     connection_id: str
     connection_addr: Optional[str]
@@ -67,37 +67,37 @@ def __init__(self, connection_id: str, connection_addr: Optional[str] = None):
         self.connection_addr = connection_addr
 
     def __repr__(self) -> str:
-        return f"PrivateLinkDeployment(connection_id={self.connection_id}, connection_addr={self.connection_addr})"
+        return f"ClientRoutesContactPoint(connection_id={self.connection_id}, connection_addr={self.connection_addr})"
 
 
 class ClientRoutesConfig:
     """
     Configuration for client routes (Private Link support).
 
-    :param deployments: List of :class:`PrivateLinkDeployment` objects
-        (REQUIRED, at least one)
+    :param contact_points: List of ClientRoutesContactPoint objects (REQUIRED, at least one)
+    :param cache_ttl_seconds: How long DNS resolution results are cached (default: 300 seconds = 5 minutes)
     """
 
-    deployments: List[PrivateLinkDeployment]
-
-    def __init__(self, deployments: List[PrivateLinkDeployment]):
+    def __init__(self, contact_points: List[ClientRoutesContactPoint],
+                 cache_ttl_seconds: int = 300):
         """
-        :param deployments: List of PrivateLinkDeployment objects
+        :param contact_points: List of ClientRoutesContactPoint objects
+        :param cache_ttl_seconds: DNS cache TTL in seconds (must be >= 0, default: 300 = 5 minutes)
         """
-        if not deployments:
-            raise ValueError("At least one deployment must be specified")
+        if not contact_points:
+            raise ValueError("At least one contact point must be specified")
 
-        if not isinstance(deployments, (list, tuple)):
-            raise TypeError("deployments must be a list or tuple")
+        if not isinstance(contact_points, (list, tuple)):
+            raise TypeError("contact_points must be a list or tuple")
 
-        for dep in deployments:
-            if not isinstance(dep, PrivateLinkDeployment):
-                raise TypeError("All deployments must be PrivateLinkDeployment instances")
+        for cp in contact_points:
+            if not isinstance(cp, ClientRoutesContactPoint):
+                raise TypeError("All contact_points must be ClientRoutesContactPoint instances")
 
-        self.deployments = list(deployments)
+        self.contact_points = list(contact_points)
 
     def __repr__(self) -> str:
-        return f"ClientRoutesConfig(deployments={self.deployments})"
+        return f"ClientRoutesConfig(contact_points={self.contact_points})"
 
 
 @dataclass
@@ -214,7 +214,7 @@ class _ClientRoutesHandler:
     config: 'ClientRoutesConfig'
     ssl_enabled: bool
     _routes: _RouteStore
-    _initial_endpoints: Set[str]
+    _initial_contact_points: Set[str]
     _dns_cache: Dict[str, Tuple[str, float]]
     _dns_cache_lock: threading.Lock
 
@@ -229,7 +229,7 @@ def __init__(self, config: 'ClientRoutesConfig', ssl_enabled: bool = False):
         self.config = config
         self.ssl_enabled = ssl_enabled
         self._routes = _RouteStore()
-        self._connection_ids = {dep.connection_id for dep in config.deployments}
+        self._initial_contact_points = {dep.connection_id for dep in config.contact_points}
 
     def initialize(self, control_connection: 'ControlConnection') -> None:
         """
@@ -240,10 +240,10 @@ def initialize(self, control_connection: 'ControlConnection') -> None:
 
         :param control_connection: The ControlConnection instance
         """
-        log.info("[client routes] Initializing with %d deployments", len(self.config.deployments))
+        log.info("[client routes] Initializing with %d contact points", len(self.config.contact_points))
 
         try:
-            connection_ids = self._connection_ids
+            connection_ids = self._initial_contact_points
             routes = self._query_routes(control_connection, connection_ids=connection_ids)
 
             self._routes.update(routes)
@@ -267,7 +267,7 @@ def handle_client_routes_change(self, control_connection: 'ControlConnection',
         """
         filtered_conn_ids = None
         if connection_ids:
-            configured_ids = self._connection_ids
+            configured_ids = self._initial_contact_points
             filtered = [cid for cid in connection_ids if cid in configured_ids]
             if not filtered:
                 return
@@ -301,7 +301,7 @@ def handle_control_connection_reconnect(self, control_connection: 'ControlConnec
         """
         log.info("[client routes] Control connection reconnected, reloading all routes")
 
-        connection_ids = self._connection_ids
+        connection_ids = self._initial_contact_points
         max_attempts = 3
         for attempt in range(1, max_attempts + 1):
             try:

cassandra/cluster.py

@@ -1311,12 +1311,12 @@ def __init__(self,
             self._client_routes_handler = _ClientRoutesHandler(client_routes_config, ssl_enabled=ssl_enabled)
 
             if contact_points is _NOT_SET or not self._contact_points_explicit:
-                seed_addrs = [dep.connection_addr for dep in client_routes_config.deployments
-                             if dep.connection_addr]
+                seed_addrs = [cp.connection_addr for cp in client_routes_config.contact_points
+                             if cp.connection_addr]
                 if seed_addrs:
                     self.contact_points = seed_addrs
                     self._contact_points_explicit = True
-                    log.info("[client routes] Using %d deployment connection addresses as contact points",
+                    log.info("[client routes] Using %d contact point connection addresses as seed contact points",
                             len(seed_addrs))
 
         if self._client_routes_handler is not None:

tests/integration/standard/test_client_routes.py

@@ -39,7 +39,7 @@
 import urllib.request
 
 from cassandra.cluster import Cluster
-from cassandra.client_routes import ClientRoutesConfig, PrivateLinkDeployment
+from cassandra.client_routes import ClientRoutesConfig, ClientRoutesContactPoint
 from cassandra.connection import ClientRoutesEndPoint
 from cassandra.policies import RoundRobinPolicy
 from tests.integration import (
@@ -573,7 +573,7 @@ class TestGetHostPortMapping(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
         cls.cluster = TestCluster(client_routes_config=ClientRoutesConfig(
-            deployments=[PrivateLinkDeployment("conn_id", "127.0.0.1")]))
+            contact_points=[ClientRoutesContactPoint("conn_id", "127.0.0.1")]))
         cls.session = cls.cluster.connect()
 
         cls.host_ids = [uuid.uuid4() for _ in range(3)]
@@ -701,8 +701,8 @@ def _make_client_routes_cluster(self, **extra_kwargs):
             contact_points=[NLBEmulator.LISTEN_HOST],
             port=self.nlb.discovery_port,
             client_routes_config=ClientRoutesConfig(
-                deployments=[PrivateLinkDeployment(self.connection_id, NLBEmulator.LISTEN_HOST)],
-
+                contact_points=[ClientRoutesContactPoint(self.connection_id, NLBEmulator.LISTEN_HOST)],
+                cache_ttl_seconds=0,
             ),
             load_balancing_policy=RoundRobinPolicy(),
             **extra_kwargs,
@@ -823,8 +823,8 @@ def test_route_update_causes_reconnect_to_new_port(self):
                 contact_points=[NLBEmulator.LISTEN_HOST],
                 port=nlb_v1.discovery_port,
                 client_routes_config=ClientRoutesConfig(
-                    deployments=[PrivateLinkDeployment(self.connection_id, NLBEmulator.LISTEN_HOST)],
-
+                    contact_points=[ClientRoutesContactPoint(self.connection_id, NLBEmulator.LISTEN_HOST)],
+                    cache_ttl_seconds=0,
                 ),
                 load_balancing_policy=RoundRobinPolicy(),
             ) as cluster:
@@ -956,8 +956,8 @@ def test_mixed_direct_and_nlb_connections(self):
             with Cluster(
                 contact_points=["127.0.0.1"],
                 client_routes_config=ClientRoutesConfig(
-                    deployments=[PrivateLinkDeployment(self.connection_id, NLBEmulator.LISTEN_HOST)],
-
+                    contact_points=[ClientRoutesContactPoint(self.connection_id, NLBEmulator.LISTEN_HOST)],
+                    cache_ttl_seconds=0,
                 ),
                 load_balancing_policy=RoundRobinPolicy(),
             ) as cluster:
@@ -1087,8 +1087,8 @@ def routes_visible():
                 port=nlb.discovery_port,
                 ssl_context=ssl_ctx,
                 client_routes_config=ClientRoutesConfig(
-                    deployments=[PrivateLinkDeployment(self.connection_id, NLBEmulator.LISTEN_HOST)],
-
+                    contact_points=[ClientRoutesContactPoint(self.connection_id, NLBEmulator.LISTEN_HOST)],
+                    cache_ttl_seconds=0,
                 ),
                 load_balancing_policy=RoundRobinPolicy(),
             ) as cluster:
@@ -1119,7 +1119,7 @@ def test_ssl_with_hostname_verification_raises_error(self):
                 contact_points=[NLBEmulator.LISTEN_HOST],
                 ssl_context=ssl_ctx,
                 client_routes_config=ClientRoutesConfig(
-                    deployments=[PrivateLinkDeployment("test-id", NLBEmulator.LISTEN_HOST)],
+                    contact_points=[ClientRoutesContactPoint("test-id", NLBEmulator.LISTEN_HOST)],
                 ),
             )
         self.assertIn("check_hostname", str(cm.exception))
@@ -1177,8 +1177,8 @@ def test_should_survive_full_node_replacement_through_nlb(self):
                 contact_points=[NLBEmulator.LISTEN_HOST],
                 port=nlb.discovery_port,
                 client_routes_config=ClientRoutesConfig(
-                    deployments=[PrivateLinkDeployment(self.connection_id, NLBEmulator.LISTEN_HOST)],
-
+                    contact_points=[ClientRoutesContactPoint(self.connection_id, NLBEmulator.LISTEN_HOST)],
+                    cache_ttl_seconds=0,
                 ),
                 load_balancing_policy=RoundRobinPolicy(),
             ) as cluster:

tests/unit/test_client_routes.py

@@ -18,7 +18,7 @@
 from unittest.mock import Mock, patch
 
 from cassandra.client_routes import (
-    PrivateLinkDeployment,
+    ClientRoutesContactPoint,
     ClientRoutesConfig,
     _RouteStore,
     _Route,
@@ -29,29 +29,35 @@
 from cassandra import DriverException
 
 
-class TestPrivateLinkDeployment(unittest.TestCase):
+class TestClientRoutesContactPoint(unittest.TestCase):
 
     def test_endpoint_none_connection_id(self):
         with self.assertRaises(ValueError):
-            PrivateLinkDeployment(None)
+            ClientRoutesContactPoint(None)
 
 
 class TestClientRoutesConfig(unittest.TestCase):
 
-    def test_config_with_deployments(self):
-        ep1 = PrivateLinkDeployment(str(uuid.uuid4()), "10.0.0.1")
-        ep2 = PrivateLinkDeployment(str(uuid.uuid4()), "10.0.0.2")
+    def test_config_with_endpoints(self):
+        ep1 = ClientRoutesContactPoint(str(uuid.uuid4()), "10.0.0.1")
+        ep2 = ClientRoutesContactPoint(str(uuid.uuid4()), "10.0.0.2")
         config = ClientRoutesConfig([ep1, ep2])
-        self.assertEqual(len(config.deployments), 2)
+        self.assertEqual(len(config.contact_points), 2)
 
-    def test_config_empty_deployments(self):
+    def test_config_empty_contact_points(self):
         with self.assertRaises(ValueError):
             ClientRoutesConfig([])
 
-    def test_config_invalid_deployment_type(self):
+    def test_config_invalid_contact_point_type(self):
         with self.assertRaises(TypeError):
-            ClientRoutesConfig(["not-a-deployment"])
+            ClientRoutesConfig(["not-a-contact-point"])
 
+    def test_config_cache_ttl_validation(self):
+        ep = ClientRoutesContactPoint(str(uuid.uuid4()))
+        with self.assertRaises(ValueError):
+            ClientRoutesConfig([ep], cache_ttl_seconds=-1)
+        config = ClientRoutesConfig([ep], cache_ttl_seconds=0)
+        self.assertEqual(config.cache_ttl_seconds, 0)
 
 
 class TestRouteStore(unittest.TestCase):
@@ -98,8 +104,8 @@ class TestClientRoutesHandler(unittest.TestCase):
 
     def setUp(self):
         self.conn_id = uuid.uuid4()
-        self.deployment = PrivateLinkDeployment(str(self.conn_id), "10.0.0.1")
-        self.config = ClientRoutesConfig([self.deployment])
+        self.endpoint = ClientRoutesContactPoint(str(self.conn_id), "10.0.0.1")
+        self.config = ClientRoutesConfig([self.endpoint])
 
     def test_handler_initialization(self):
         handler = _ClientRoutesHandler(self.config, ssl_enabled=False)
@@ -132,8 +138,8 @@ class TestClientRoutesEndPoint(unittest.TestCase):
 
     def setUp(self):
         self.conn_id = uuid.uuid4()
-        self.deployment = PrivateLinkDeployment(str(self.conn_id), "10.0.0.1")
-        self.config = ClientRoutesConfig([self.deployment])
+        self.endpoint_entry = ClientRoutesContactPoint(str(self.conn_id), "10.0.0.1")
+        self.config = ClientRoutesConfig([self.endpoint_entry])
         self.handler = _ClientRoutesHandler(self.config, ssl_enabled=False)
 
     def test_resolve_falls_back_when_no_mapping(self):
@@ -155,7 +161,7 @@ def test_check_hostname_with_ssl_context_raises(self):
         self.assertTrue(ssl_ctx.check_hostname)
 
         config = ClientRoutesConfig(
-            deployments=[PrivateLinkDeployment(str(uuid.uuid4()), "10.0.0.1")]
+            contact_points=[ClientRoutesContactPoint(str(uuid.uuid4()), "10.0.0.1")]
         )
         with self.assertRaises(ValueError) as cm:
             Cluster(
@@ -168,7 +174,7 @@ def test_check_hostname_with_ssl_context_raises(self):
     def test_check_hostname_with_ssl_options_raises(self):
         """Cluster should reject check_hostname=True in ssl_options with client_routes_config."""
         config = ClientRoutesConfig(
-            deployments=[PrivateLinkDeployment(str(uuid.uuid4()), "10.0.0.1")]
+            contact_points=[ClientRoutesContactPoint(str(uuid.uuid4()), "10.0.0.1")]
         )
         with self.assertRaises(ValueError) as cm:
             Cluster(
@@ -184,7 +190,7 @@ def test_disabled_check_hostname_with_client_routes_ok(self):
         ssl_ctx.check_hostname = False
 
         config = ClientRoutesConfig(
-            deployments=[PrivateLinkDeployment(str(uuid.uuid4()), "10.0.0.1")]
+            contact_points=[ClientRoutesContactPoint(str(uuid.uuid4()), "10.0.0.1")]
         )
         # Should not raise
         cluster = Cluster(
@@ -197,7 +203,7 @@ def test_disabled_check_hostname_with_client_routes_ok(self):
     def test_no_ssl_with_client_routes_ok(self):
         """Cluster should allow client_routes_config without SSL."""
         config = ClientRoutesConfig(
-            deployments=[PrivateLinkDeployment(str(uuid.uuid4()), "10.0.0.1")]
+            contact_points=[ClientRoutesContactPoint(str(uuid.uuid4()), "10.0.0.1")]
         )
         # Should not raise
         cluster = Cluster(