# Client Routes (ScyllaDB Cloud Private Connectivity)

When connecting to clusters with ScyllaDB Cloud Private Connectivity,
a ScyllaDB feature provided using AWS PrivateLink or GCP Private Service Connect,
nodes are not reachable at the addresses they broadcast to each other.
Instead, each node is reachable through a proxy endpoint whose address is stored in the
`system.client_routes` table. The driver needs to be told to use this table for routing —  that is
what the **Client Routes** feature provides.

## Overview

In a Client Routes setup:

1. Each proxy endpoint is identified by a **connection ID** —  a string that the cloud
   infrastructure assigns to a particular PrivateLink / Private Service Connect connection.
2. On session startup, as well as on each metadata refresh, the driver queries `system.client_routes`
   to discover which (address, port) pair to use for each cluster node, filtering by the configured
   connection IDs.
3. The driver subscribes to `CLIENT_ROUTES_CHANGE` events so it can update routing
   information without a full metadata refresh when the table contents change.

### Limitations

1. Mixed clusters (with both nodes reachable only through ClientRoutes and nodes reachable only directly)
   **are not supported**. All nodes must be reachable through ClientRoutes, in particular have corresponding
   entries in `system.client_routes`; otherwise, the driver will fail to contact them.
2. TLS **is not yet supported**.

## Prerequisites

Enable the `unstable-client-routes` Cargo feature:

```toml
[dependencies]
scylla = { version = "...", features = ["unstable-client-routes"] }
```

## Basic usage

```rust
use scylla::client::client_routes::{ClientRoutesConfig, ClientRoutesProxy};
use scylla::client::session::Session;
use scylla::client::session_builder::ClientRoutesSessionBuilder;

// The connection ID assigned by your cloud provider for this PrivateLink /
// Private Service Connect connection.
let connection_id = "my-connection-id".to_string();

// Create a proxy configuration for this connection ID.
let proxy = ClientRoutesProxy::new_with_connection_id(connection_id);

// Build a ClientRoutesConfig (at least one proxy is required).
let config = ClientRoutesConfig::new(vec![proxy])?;

// Build the session.  Use the contact point(s) provided by your cloud setup.
let session: Session = ClientRoutesSessionBuilder::new(config)
    .known_node("my-privatelink-endpoint.amazonaws.com:9042")
    .build()
    .await?;

```

## Multiple connection IDs

If your deployment routes traffic through more than one proxy (e.g. one per availability zone),
pass all of them:

```rust
use scylla::client::client_routes::{ClientRoutesConfig, ClientRoutesProxy};
use scylla::client::session::Session;
use scylla::client::session_builder::ClientRoutesSessionBuilder;

let proxies = vec![
    ClientRoutesProxy::new_with_connection_id("conn-id-az-1".into()),
    ClientRoutesProxy::new_with_connection_id("conn-id-az-2".into()),
];

let config = ClientRoutesConfig::new(proxies)?;

let session: Session = ClientRoutesSessionBuilder::new(config)
    .known_node("endpoint-az-1.amazonaws.com:9042")
    .known_node("endpoint-az-2.amazonaws.com:9042")
    .build()
    .await?;

```

## Overriding the hostname

By default, the hostname for each proxy is read from `system.client_routes`.
You can override it if your environment requires a different DNS name or IP
(e.g. for local testing):

```rust
use scylla::client::client_routes::{ClientRoutesConfig, ClientRoutesProxy};
use scylla::client::session::Session;
use scylla::client::session_builder::ClientRoutesSessionBuilder;

let proxy = ClientRoutesProxy::new_with_connection_id("my-connection-id".into())
    .with_overridden_hostname("127.0.0.1".into());

let config = ClientRoutesConfig::new(vec![proxy])?;

let session: Session = ClientRoutesSessionBuilder::new(config)
    .known_node("127.0.0.1:9042")
    .build()
    .await?;

```

## Differences from a regular session

`ClientRoutesSessionBuilder` supports most of the same options as the regular `SessionBuilder`
(compression, authentication, execution profiles, etc.) with two exceptions:

* **Address translation** is managed internally by the Client Routes infrastructure,
  so `address_translator()` is not available.
* **TLS** is not yet supported on Client Routes sessions.

Additionally, *advanced shard awareness* (the driver choosing a source port to target a specific
shard) is disabled by default because the proxy infrastructure does not preserve it.
**Note:** *basic shard awareness* still works, meaning that driver routes requests optimally - to
the correct shards.
