fix: connect via all DNS IPs when first contact point is non-responsive (DRIVER-201)

[nikagra]

Problem

When RESOLVE_CONTACT_POINTS=false (the default), a contact point hostname is stored as a single unresolved InetSocketAddress. At connection time, ChannelFactory passed this address directly to Netty's bootstrap.connect(), which internally called InetAddress.getByName() — returning only the first IP for the hostname. If that IP was non-responsive, the driver raised AllNodesFailedException with no fallback to other IPs the hostname might resolve to.

This is particularly impactful in dynamic DNS environments where a hostname can map to multiple nodes and the first one may be temporarily unavailable.

Fixes DRIVER-201.

Changes

ChannelFactory.java

Refactored the connection logic using the Parameter Object pattern and SRP decomposition:

• ConnectRequest inner class: bundles all per-connection-attempt state, eliminating the unwieldy 9-parameter private connect() method.
• connect(ConnectRequest): resolves the endpoint address. For unresolved hostnames, calls InetAddress.getAllByName() to expand to all known IPs, building a candidate list. DNS resolution is still deferred to connection time — the EndPoint continues to hold the unresolved hostname — preserving the dynamic-DNS semantics of RESOLVE_CONTACT_POINTS=false.
• tryNextAddress(request, candidates, index): iterates the candidate list. On per-address failure it tries the next candidate; only when all are exhausted does it fail the overall resultFuture.
• connectToAddress(request, address): performs a single Netty bootstrap connect to one resolved IP. Protocol-version negotiation (downgrade retries) is scoped to the same IP, which is semantically correct. Returns its own CompletableFuture<DriverChannel> so tryNextAddress can distinguish a per-address failure from the final outcome.
• tryNextAddressRaw: unchanged pass-through for non-InetSocketAddress types (e.g. Unix domain sockets).

MockResolverIT.java

New integration test should_connect_when_first_dns_entry_is_non_responsive:

• 2-node CCM cluster on 127.0.1.x
• test.cluster.fake resolves to 127.0.1.11 (non-existent) first, then nodes 1 and 2
• RESOLVE_CONTACT_POINTS=false, RECONNECT_ON_INIT=false
• Asserts the session opens successfully and both nodes come up despite the first DNS entry being unreachable

[Copilot]

Pull request overview

This PR addresses DRIVER-201 by improving initial contact point connection behavior when RESOLVE_CONTACT_POINTS=false, ensuring that if a hostname resolves to multiple IPs and the first is unreachable, the driver can fall back to subsequent IPs instead of failing immediately.

Changes:

• Refactors ChannelFactory connection logic to expand unresolved hostnames to all DNS IPs at connection time and attempt them sequentially.
• Introduces a ConnectRequest parameter object and decomposes connection steps into smaller methods.
• Adds an integration test covering the “first DNS A record is unreachable” scenario.

Reviewed changes

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

File	Description
core/src/main/java/com/datastax/oss/driver/internal/core/channel/ChannelFactory.java	Expands unresolved hostnames to all resolved IPs at connect time and adds sequential fallback across addresses.
integration-tests/src/test/java/com/datastax/oss/driver/core/resolver/MockResolverIT.java	Adds an integration test to validate successful connection when the first DNS entry is non-responsive.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dkropachev]

@nikagra , you solve it too deep in the driver, probably the best place is newControlReconnectionQueryPlan, you just need to re-resolve unresolved DNS endpoints there creating a fake Node for each of the resolved ip.

[nikagra]

@dkropachev Thanks for the suggestion. I considered your approach, but the issue description identifies the root cause specifically at bootstrap.connect, which is called only from ChannelFactory. Fixing it there addresses the problem at its source and covers all connection paths (control connection, pool, reconnection), not just the control connection init. The approach proposed by you if I understand it right, would require synthetic Node objects and still leave the same underlying Netty limitation in place for ChannelPool direct calls.

[dkropachev]

@dkropachev Thanks for the suggestion. I considered your approach, but the issue description identifies the root cause specifically at bootstrap.connect, which is called only from ChannelFactory. Fixing it there addresses the problem at its source and covers all connection paths (control connection, pool, reconnection), not just the control connection init. The approach proposed by you if I understand it right, would require synthetic Node objects and still leave the same underlying Netty limitation in place for ChannelPool direct calls.

There are two instances for this issue and I would recomended them fixed separately:

1. Initial contact endpoints
2. Endpoint.resolve

Here is what should be done to address Initial contact endpoints:

1. Depricate and stop honoring DefaultDriverOption.RESOLVE_CONTACT_POINTS
2. Have another method near MetadataManager.getContactPoints that resolves MetadataManager.contactPoints before hading them over
3. Use that method everywhere where MetadataManager.getContactPoints is currently called

In regards of the Endpoint.resolve we should just expand API:

    @Deprecated
    @NonNull
    SocketAddress resolve();

    @NonNull
    default SocketAddress[] resolveAll() {
        return new SocketAddress[] { resolve() };
    }

And implement resolveAll() for endpoints that resolved from DNS, such as ClientRoutesEndPoint and SniEndPoint.
In total it should be 2-3 PRs