Skip to content

Race connection attempts across resolved addresses for the Classic client (RFC 8305) - #936

Open
arturobernalg wants to merge 1 commit into
apache:masterfrom
arturobernalg:happy-eyeballs-classic
Open

arturobernalg wants to merge 1 commit into
apache:masterfrom
arturobernalg:happy-eyeballs-classic

Conversation

@arturobernalg

@arturobernalg arturobernalg commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Implements RFC 8305 (Happy Eyeballs v2) connection racing for the Classic (blocking) client, as the third and final PR of this series, alongside #935 (Async connection racing) and arturobernalg#20 (Async independent A/AAAA resolution, stacked on #935 pending its merge). This PR is independent of the other two: the Classic client has its own connection path (java.net.Socket, not the reactor), so it needed its own, smaller mechanism rather than reusing the Async internals.

Dependency

None. Based directly on upstream master, independent of #935 and arturobernalg#20.

@arturobernalg

Copy link
Copy Markdown
Member Author

Validated the racing mechanism and fallback timing against real clients over real hosts:

Client Native Happy Eyeballs Stagger/delay
This PR Yes 250ms (RFC 8305 recommended)
Go net.Dialer Yes 300ms (hardcoded)
curl/libcurl Yes, since 7.59 200ms default
Java (plain JDK) No —

Same race semantics in all three that have it; winner differs only by each client's own DNS ordering (v4 vs v6), not by the racing logic. Fallback timing confirmed with a stalled address + real local listener: 266ms, matching the 250ms stagger. Also marked the opt-in setters @Experimental.

@arturobernalg
arturobernalg requested a review from ok2c November 14, 2026 16:53
@ok2c

ok2c commented Nov 14, 2026

Copy link
Copy Markdown
Member

@arturobernalg This feature was requested by @rschmitt I am not sure I am able to review this or any of the related pull requests.

@arturobernalg

Copy link
Copy Markdown
Member Author

Ryan hasn't been around in a long time, so I don't think we should block on that. I've tested this thoroughly - real fallback timing, live comparisons against Go's net.Dialer and curl's native Happy Eyeballs across multiple hosts, concurrency stress tests on the race/cleanup paths - and I'm confident it's correct and behaves as intended. Happy to walk through any specific part you're unsure about.

@ok2c

ok2c commented Nov 14, 2026

Copy link
Copy Markdown
Member

@arturobernalg This is true @rschmitt has not been around much, but he has not resigned from the project either. Invite him to review the pull requests. If he does not respond, feel free to merge them but please keep this feature as opt-in, at least initially. I would also wait until 5.8 unless you have pressing reasons to put this feature into 5.7.

@ok2c

ok2c commented Nov 14, 2026

Copy link
Copy Markdown
Member

@arturobernalg And please fix the deprecation warnings

@arturobernalg

Copy link
Copy Markdown
Member Author

Sounds good, will target 5.8 then. @rschmitt if you get a chance, would appreciate you taking a look at this new version - opt-in, disabled by default.

@shinseongsu

Copy link
Copy Markdown
Contributor

@arturobernalg I tried the racing path against a host where one address accepts TCP but fails the TLS handshake, and wanted to check whether this is intended.

With two addresses, where the first completes the TCP handshake but the TLS handshake fails and the second is healthy:

  • Happy Eyeballs off: the TLS failure on the first address is caught in the sequential loop and the second address is used, same as on master.
  • Happy Eyeballs on: the first address wins the race as soon as TCP connects, the other attempts are cancelled, and the TLS failure goes straight to the caller. The second address is never tried.

The winner is picked on TCP connect in HappyEyeballsSocketConnector (L187). upgradeToTls then runs once outside the race (L272), and its catch closes the socket and rethrows.

I measured it end to end with the classic client, a new connection per request. DNS returns [127.0.0.1, ::1] on the same port. 127.0.0.1 accepts TCP and then resets or stalls, and ::1 is a working TLS server.

master this PR, HE off this PR, HE on
127.0.0.1 resets after accept (100 requests) 100 OK 100 OK 0 OK, 100 SocketException
127.0.0.1 stalls the handshake (10 requests) 10 OK 10 OK 0 OK, 10 SocketTimeoutException

A packet capture of the HE-on runs shows no SYN to ::1 at all. With HE off, every request goes on to ::1 and completes the handshake there.

Here is a test that runs the same case against the operator directly. It passes with happyEyeballs=false and fails with happyEyeballs=true (IOException: handshake failed on localhost/127.0.0.1:...):

HappyEyeballsTlsFallbackProbeTest
@ParameterizedTest(name = "happyEyeballs={0}")
@ValueSource(booleans = {false, true})
void tlsFailureOnFirstAddressFallsBackToNextAddress(final boolean happyEyeballs) throws Exception {
    try (ServerSocket broken = new ServerSocket(0, 50, InetAddress.getLoopbackAddress());
         ServerSocket healthy = new ServerSocket(0, 50, InetAddress.getLoopbackAddress())) {
        final List<InetSocketAddress> remoteAddresses = Arrays.asList(
                new InetSocketAddress(InetAddress.getLoopbackAddress(), broken.getLocalPort()),
                new InetSocketAddress(InetAddress.getLoopbackAddress(), healthy.getLocalPort()));
        final DnsResolver dnsResolver = Mockito.mock(DnsResolver.class);
        Mockito.when(dnsResolver.resolve(Mockito.anyString(), Mockito.anyInt())).thenReturn(remoteAddresses);

        final AtomicInteger handshakes = new AtomicInteger();
        final AtomicInteger upgradedPort = new AtomicInteger();
        final TlsSocketStrategy tls = (socket, target, port, attachment, context) -> {
            handshakes.incrementAndGet();
            if (socket.getPort() == broken.getLocalPort()) {
                throw new IOException("handshake failed on " + socket.getRemoteSocketAddress());
            }
            upgradedPort.set(socket.getPort());
            return Mockito.mock(SSLSocket.class);
        };
        final Lookup<TlsSocketStrategy> tlsLookup = scheme -> tls;

        final DefaultHttpClientConnectionOperator operator = new DefaultHttpClientConnectionOperator(
                proxy -> new Socket(), DefaultSchemePortResolver.INSTANCE, dnsResolver, tlsLookup,
                happyEyeballs, TimeValue.ofMilliseconds(250));
        final DefaultManagedHttpClientConnection conn = new DefaultManagedHttpClientConnection(
                "test", null, null, null, null, null, null, null, null);

        operator.connect(conn, new HttpHost("https", "somehost", 443), null,
                TimeValue.ofSeconds(5), SocketConfig.DEFAULT, HttpClientContext.create());

        assertEquals(healthy.getLocalPort(), upgradedPort.get());
        assertEquals(2, handshakes.get());
    }
}

I can see arguments for this being intended. RFC 8305 section 5 counts an attempt as successful once the TCP handshake completes, and section 9 leaves TLS failures out of scope. happyEyeballsRacing_tlsHandshakeFailure_closesWinningSocket also expects the IOException. The async client on master doesn't move to the next address after a TLS failure either. On the other hand, with the classic client enabling Happy Eyeballs makes this case fail where the default path succeeds. OkHttp's FastFallbackExchangeFinder races on TCP the same way, but it defers the losing attempts and goes on to them when connectTlsEtc() fails on the winner.

Is the HE-on behavior what you want here? If so, maybe it's worth mentioning in the javadoc for setHappyEyeballsEnabled that a TLS failure on the winning address isn't retried on the other addresses.

…ient

Replaces the one-thread-per-address, sleep-based stagger with a single
dispatcher that starts the first address immediately and waits up to
the connection attempt delay for an outstanding attempt to finish
before starting the next; on a failure it advances immediately, at the
RFC 8305 minimum spacing (10ms), instead of waiting out the full delay.
No worker thread ever sleeps a delay itself, bounding concurrency to
the number of resolved addresses actually in flight.

Socket registration goes through a small atomic registry instead of a
bare reference: deciding a winner and a worker registering its socket
can happen at the same instant, and whichever runs second closes the
socket, so nothing registered around that moment survives open
regardless of timing. shutdownNow() alone cannot abort a blocking
Socket#connect; closing the socket is what actually does that, on
every exit path (winner found, every address failed, or interrupted)
via one cleanup call in a finally block.

An interruption during the minimum-spacing wait is now propagated
instead of swallowed, aborting the race immediately like interruption
anywhere else in it. Racing is skipped in favor of the existing
sequential path when a specific, non-ephemeral local port is
requested, since binding several attempts to it concurrently would
trade a real connect failure for a spurious bind conflict.

Public, blocking connect() behavior, TLS, SOCKS and local binding are
otherwise unchanged.
@arturobernalg

Copy link
Copy Markdown
Member Author

@shinseongsu Confirmed, reproduced end to end with real TCP/TLS servers — same exceptions you measured.

Fixed: on TLS failure after the race picks a winner, the operator now falls back to the remaining addresses, same as the non-racing path. HappyEyeballsSocketConnector untouched — still pure TCP racing.

Async doesn't do this either and RFC 8305 §9.2 leaves it out of scope, but the Classic client already guaranteed it before this PR, so dropping it under Happy Eyeballs would've been a silent regression. Added your test plus a couple more. Pushed.

@shinseongsu

Copy link
Copy Markdown
Contributor

@arturobernalg Thanks for the quick fix. I reran everything on 4d1e562. The probe test now passes with Happy Eyeballs both on and off, and the end-to-end runs with HE on are all OK: 100/100 when 127.0.0.1 resets, 10/10 when it stalls. The capture shows each request moving on to ::1 and finishing the handshake there.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants