Add `ControlConnectionQueryFallback` option

[patrycja-ziemkiewicz]

Add ControlConnectionQueryFallback option

Summary

Add an option to allow routing application queries through the control connection when node connection pools are unavailable, similar to the Python driver's ControlConnectionQueryFallback.

Background

The Python driver provides a ControlConnectionQueryFallback setting on the Cluster object with three modes:

• Disabled (default) - requires a usable node pool for application queries. If none is available, the driver raises NoHostAvailable.
• Fallback - still attempts to create node pools, but allows application queries to fall back to the control connection when no usable pool is available. Session startup proceeds even if all initial pool attempts fail.
• SkipPoolCreation - disables node-pool creation entirely and routes all application queries through the control connection.

Current state in the Rust driver

The Rust driver's ControlConnection is used exclusively for metadata fetching and event listening. There is currently no way to route user queries through it when connection pools are unavailable, the driver will return a connection error instead.

References

• Python driver implementation: cassandra.cluster.ControlConnectionQueryFallback (source)
• Related UDS discussion: being able to skip pool creation is a prerequisite for single-connection usage over Unix domain sockets : Feature request: Unix domain socket support #1616

[Lorak-mmk]

In Rust Driver I would take a different approach than in Python, specifically lets skip the "Fallback" mode. I think using it is invalid most of the time, or even always.

A single-node session (where only CC address works) is only feasible for workloads where performance doesn't matter, like CQLSH, some heartbeats, DDLs, fetching schema.
If you need performance, you need normal session, and CC fallback is useless.
If you don't need performance, then using the simplified session makes more sense (it should connect faster, use less resources, have less problems).

Another observation: Unix proxy only makes sense for single-node session.

Because of all that, one idea I have for public API is simply a new field in SessionConfig, maintenance_mode, which is either None, or Some storing a single contact point (in which case normal contact points must be empty). This single contact point may be a unix socket (in addition to IP address / DNS name).
For implementation, we can either share a single CC (more difficult) or have a CC + a NodeConnectionPool opened to the same address as CC (imo simpler and good enough for now).

You'll still need to figure out many details, I'm sure @wprzytula will help.

[patrycja-ziemkiewicz]

Notes on possible approaches

I think we should first decide whether we want to treat this as one combined feature, or as two separate features:

1. Support executing queries through the control connection.
2. Support a maintenance/single-connection session mode, including Unix domain sockets.

These overlap, but they are not exactly the same problem.

For Unix socket sessions, the issue description explicitly says that topology refresh and connected operations should be disabled. In that model, a full regular Session with metadata refreshes, Cluster, node discovery, token metadata, etc. does not seem very useful.

For control-connection fallback, the use case may be different. It is not yet clear whether users would always want the same restricted "maintenance mode" semantics, or whether they would expect a mostly normal session that can only use the control connection for query execution.

Approach 1: Use Session

This would keep the regular Session as the public object.

Possible shape:

let session = SessionBuilder::new()
    .maintenance_mode(...)
    .build()
    .await?;

The problem is that a regular Session currently implies a lot of cluster-level behavior:

• metadata refreshes
• topology refresh
• access to Cluster
• node objects
• peer/local table reads
• token and host-id metadata
• connection pools
• TLS-related configuration

For Unix socket sessions, most of this does not make much sense.

Unix sockets do not have a SocketAddr, but the current node model assumes address-based nodes. Adding a PathBuf variant to NodeAddr or exposing it through the existing public API would likely be a breaking API change, also Coordinator needs connection_address which is SocketAddr.

If we tried to fit Unix sockets into the current model, we would probably need dummy values:

• dummy IP address
• dummy node UUID
• dummy token metadata

That would work internally, but it would expose misleading data if the user inspects the Cluster or node metadata.

If we keep this approach but disable topology refresh and avoid using the control connection, then we would not need to query system.local and system.peers. However, we would still need to decide what to expose through Session and Cluster.

Main concern: this approach may expose too much regular-session functionality for a mode where most of it is invalid or misleading.

Approach 2: Separate session-like abstraction using existing request execution path

Another option is to introduce a different public object for maintenance sessions, while still reusing parts of the existing request execution pipeline.

For example, internally this could operate around RequestExecutionParams and still reuse NodeConnectionPool.

This has the benefit of reusing existing logic:

• request execution
• connection acquisition
• pool refill logic
• retry/reconnection behavior where applicable

For Unix sockets, we would still have the problem that RequestExecutionParams currently expects a Node, and Node expects address-like metadata. That means we may still need some dummy node/address representation internally unless we refactor that layer.

Approach 3: Thin maintenance layer directly on top of Connection

This would be a simpler dedicated path for maintenance sessions.

The maintenance session would communicate almost directly through a Connection, without exposing most of the regular Session functionality. It could also try to reuse the existing NodeConnectionPool logic for reconnecting/refilling connections.

This seems natural for Unix socket use cases:

• single connection
• no topology refresh
• no token metadata
• no Cluster
• no node discovery
• no regular node pools
• no misleading dummy metadata exposed to the user

The open question is whether this thinner set of functionality is also what we want for users who only want to execute through the control connection. For Unix sockets, the restricted maintenance-session model seems natural. For control-connection query execution, it is less clear whether users expect this restricted behavior or a more regular Session-like API.

Approach 4: Query execution abstraction on top of ControlConnection

This would be closest to the original "query through control connection" idea.

We could expose some abstraction that allows application queries to be executed using the existing ControlConnection.

Making it a query execution path would require implementing a lot of interactions around the control connection that it currently does not need to support.

This may also blur the responsibility of the control connection. It would no longer be only a driver-internal metadata/event component.

Open question

Should we combine these two features into one concept, for example maintenance_mode, or should they stay separate?

The Unix socket issue clearly points toward a restricted single-node/single-connection mode with topology refresh and connected operations disabled.

The control-connection fallback issue may or may not imply the same restrictions. We need to decide whether "execute through control connection" is intended only for maintenance-style workloads, or whether it should behave like a regular session with a different connection source.

My current understanding is:

• If the goal is Unix socket support, a dedicated maintenance session seems cleaner than forcing it into regular Session.
• If the goal is Python-like ControlConnectionQueryFallback, then we only want the SkipPoolCreation-like functionality, not all three Python modes. However, in the Python driver this does not disable metadata fetching/topology refresh, so we need to decide whether the Rust driver should behave similarly or whether SkipPoolCreation should imply a stricter maintenance mode.
• If maintenance mode is intended to cover both cases, we should define exactly which regular session features are supported and which are intentionally disabled.