Retry a refused connect on every JDK and transport

NettyConnectListener applies maxRequestRetry to a failure on a NEW
channel only when StackTraceInspector deems it recoverable, and that
check searched the cause chain for the frame
sun.nio.ch.SocketChannelImpl.checkConnect. That frame exists up to
JDK 12 only: JDK 13 moved the completion of a non-blocking connect to
sun.nio.ch.Net.pollConnect, and the native transports report the
failure as a ConnectException from io.netty.channel.unix.Errors with
no sun.nio.ch frame at all. A refused TCP connect was therefore
retried on JDK 11 with NIO and silently not retried on JDK 13, 17, 21
and 25, nor on epoll/kqueue/io_uring, which became the default where
the library is present in #2216.

Match the refusal by type as well, and keep scanning from the cause
rather than from the throwable itself: what the listener receives is
an annotating wrapper, and NettyChannelConnector wraps anything that
is not already a ConnectException in one, so the wrapper's own type
carries no information. Netty's connect timeout is a ConnectException
too and is excluded explicitly, so a blackholed host still fails after
one connectTimeout rather than maxRequestRetry of them. That
exclusion, like the whole predicate, only governs a request's first
attempt: retry() sets ChannelState.RECONNECTED, and from then on the
gate in NettyConnectListener.onFailure short-circuits on the state and
never consults the predicate. That is long-standing behaviour and is
left alone here.

Behaviour change: on JDK 13+ and on the native transports a refused
connect is retried up to maxRequestRetry again, immediately and with
DNS re-resolved per attempt, so onTcpConnectAttempt and
onTcpConnectFailure fire up to (1 + maxRequestRetry) times the number
of resolved addresses, and the time to fail against a dead port rises
accordingly. Known residual, pre-existing and not introduced here: the
native transports map ENETUNREACH and EHOSTUNREACH to a bare
NoRouteToHostException, a sibling of ConnectException with no
sun.nio.ch frame, so an unreachable peer is retried on NIO and not on
a native transport. No connect backoff is added.

Claude Code on behalf of Aayush Atharva

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: hyperxpro

client/src/main/java/org/asynchttpclient/AsyncHttpClientConfig.java

@@ -335,6 +335,10 @@ default long getMaxDecompressedResponseSize() {
     /**
      * Return the number of time the library will retry when an {@link IOException} is throw by the remote server
      *
+     * <p>A TCP connect the peer refused is retried as well, since no request byte reached it. On a
+     * request's first attempt a connect that timed out is not; from its first retry onwards any failure
+     * is. Retries are immediate, with no backoff, and the host is re-resolved for each attempt.
+     *
      * @return the number of time the library will retry when an {@link IOException} is throw by the remote server
      */
     int getMaxRequestRetry();

client/src/main/java/org/asynchttpclient/DefaultAsyncHttpClientConfig.java

@@ -1277,6 +1277,13 @@ public Builder setRealm(Realm.Builder realmBuilder) {
             return this;
         }
 
+        /**
+         * Sets how many times a request is replayed, as described by
+         * {@link AsyncHttpClientConfig#getMaxRequestRetry()}.
+         *
+         * @param maxRequestRetry the number of retries, {@code 0} to disable them
+         * @return this builder
+         */
         public Builder setMaxRequestRetry(int maxRequestRetry) {
             this.maxRequestRetry = maxRequestRetry;
             return this;

client/src/main/java/org/asynchttpclient/netty/channel/NettyConnectListener.java

@@ -328,6 +328,12 @@ private void registerHttp2AndManageSemaphore(Channel channel, ConnectionSemaphor
         }
     }
 
+    /**
+     * Invariant every caller must keep: this is only reached before {@link #writeRequest}, never after. It
+     * may replay the exchange, so a call site added after the request had been written could silently
+     * resend it. The channel is published to the handler inside writeRequest, so a later failure is
+     * reported through {@code AsyncHttpClientHandler.channelInactive} instead.
+     */
     public void onFailure(Channel channel, Throwable cause) {
 
         // beware, channel can be null

client/src/main/java/org/asynchttpclient/netty/future/StackTraceInspector.java

@@ -15,7 +15,10 @@
  */
 package org.asynchttpclient.netty.future;
 
+import io.netty.channel.ConnectTimeoutException;
+
 import java.io.IOException;
+import java.net.ConnectException;
 import java.nio.channels.ClosedChannelException;
 
 public final class StackTraceInspector {
@@ -38,7 +41,19 @@ private static boolean exceptionInMethod(Throwable t, String className, String m
 
     private static boolean recoverOnConnectCloseException(Throwable t) {
         while (true) {
-            if (exceptionInMethod(t, "sun.nio.ch.SocketChannelImpl", "checkConnect")) {
+            // A connect timeout is a ConnectException as well, but replaying it would multiply the time
+            // to fail by maxRequestRetry; only a connect the peer actually refused is replayed.
+            if (t instanceof ConnectTimeoutException) {
+                return false;
+            }
+            // Match the refusal by type as well as by frame: NIO moved the frame from
+            // SocketChannelImpl.checkConnect (JDK <= 12) to Net.pollConnect (JDK 13+), and the native
+            // transports report it with no sun.nio.ch frame at all. The frame probes are not redundant
+            // with the type check: they are what keeps an unreachable peer, reported as a
+            // NoRouteToHostException rather than a ConnectException, recoverable on NIO.
+            if (t instanceof ConnectException
+                    || exceptionInMethod(t, "sun.nio.ch.SocketChannelImpl", "checkConnect")
+                    || exceptionInMethod(t, "sun.nio.ch.Net", "pollConnect")) {
                 return true;
             }
             if (t.getCause() == null) {
@@ -49,6 +64,9 @@ private static boolean recoverOnConnectCloseException(Throwable t) {
     }
 
     public static boolean recoverOnNettyDisconnectException(Throwable t) {
+        // Deliberately scanned from the cause: the throwable handed to the connect listener is an
+        // annotating wrapper, and NettyChannelConnector wraps anything that is not already a
+        // ConnectException in one, so its own type carries no information.
         return t instanceof ClosedChannelException
                 || exceptionInMethod(t, "io.netty.handler.ssl.SslHandler", "disconnect")
                 || t.getCause() != null && recoverOnConnectCloseException(t.getCause());

client/src/test/java/org/asynchttpclient/netty/channel/ConnectFailureRetryTest.java

@@ -0,0 +1,200 @@
+/*
+ *    Copyright (c) 2026 AsyncHttpClient Project. All rights reserved.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+package org.asynchttpclient.netty.channel;
+
+import io.netty.channel.Channel;
+import io.netty.resolver.AbstractAddressResolver;
+import io.netty.resolver.AddressResolver;
+import io.netty.resolver.AddressResolverGroup;
+import io.netty.util.concurrent.EventExecutor;
+import io.netty.util.concurrent.Promise;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.apache.commons.io.IOUtils;
+import org.asynchttpclient.AbstractBasicTest;
+import org.asynchttpclient.AsyncCompletionHandler;
+import org.asynchttpclient.AsyncHttpClient;
+import org.asynchttpclient.Response;
+import org.eclipse.jetty.server.Request;
+import org.eclipse.jetty.server.handler.AbstractHandler;
+import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.net.InetAddress;
+import java.net.InetSocketAddress;
+import java.nio.charset.StandardCharsets;
+import java.util.Collections;
+import java.util.List;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import static org.asynchttpclient.Dsl.asyncHttpClient;
+import static org.asynchttpclient.Dsl.config;
+import static org.asynchttpclient.test.TestUtils.findFreePort;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+/**
+ * A TCP connect the peer refused fails before the request is written, so {@code maxRequestRetry} applies to
+ * it, on every JDK and every transport. Nothing reached the server, so the replay is safe whatever the
+ * method, and it must send the entity exactly once.
+ */
+public class ConnectFailureRetryTest extends AbstractBasicTest {
+
+    private static final String BODY = "connect-retry-body";
+
+    private final AtomicInteger requestsReceived = new AtomicInteger();
+    private final AtomicInteger bodiesReceived = new AtomicInteger();
+
+    @Override
+    public AbstractHandler configureHandler() {
+        return new CountingEchoHandler();
+    }
+
+    @Test
+    public void refusedConnectIsRetriedOnTheNextResolution() throws Exception {
+        requestsReceived.set(0);
+        // The first resolution points at a closed port, so the connect is refused before any byte is
+        // written; every later resolution points at the live server. Only a request retry can succeed.
+        SwitchingResolverGroup resolverGroup = new SwitchingResolverGroup(findFreePort(), port1);
+        try {
+            try (AsyncHttpClient client = asyncHttpClient(config()
+                    .setAddressResolverGroup(resolverGroup)
+                    .setMaxRequestRetry(1))) {
+                Response response = client.prepareGet(getTargetUrl()).execute().get(TIMEOUT, TimeUnit.SECONDS);
+                assertEquals(200, response.getStatusCode());
+                assertEquals(2, resolverGroup.resolutions(), "the refused connect was not retried");
+                assertEquals(1, requestsReceived.get(), "the refused attempt must not have reached the server");
+            }
+        } finally {
+            resolverGroup.close();
+        }
+    }
+
+    /**
+     * The replay of a refused connect has to resend the entity, and has to send it once: the first attempt
+     * never reached the server, so a duplicate here would be a duplicate POST on the wire. The connect
+     * count pins the invariant stated on {@code NettyConnectListener.onFailure} - a connect that succeeded
+     * is a request that was written, so a second success would mean a written request had been replayed.
+     */
+    @Test
+    public void refusedConnectReplaysThePostBodyExactlyOnce() throws Exception {
+        requestsReceived.set(0);
+        bodiesReceived.set(0);
+        SwitchingResolverGroup resolverGroup = new SwitchingResolverGroup(findFreePort(), port1);
+        try {
+            try (AsyncHttpClient client = asyncHttpClient(config()
+                    .setAddressResolverGroup(resolverGroup)
+                    .setMaxRequestRetry(1))) {
+                ConnectCountingHandler handler = new ConnectCountingHandler();
+                Response response = client.preparePost(getTargetUrl())
+                        .setBody(BODY)
+                        .execute(handler)
+                        .get(TIMEOUT, TimeUnit.SECONDS);
+                assertEquals(200, response.getStatusCode());
+                assertEquals(BODY, response.getResponseBody());
+                assertEquals(1, requestsReceived.get(), "the request was sent more than once");
+                assertEquals(1, bodiesReceived.get(), "the body was sent more than once");
+                assertEquals(1, handler.connectSuccesses.get(), "a written request was replayed");
+                assertEquals(1, handler.connectFailures.get(), "the refused attempt was not counted");
+            }
+        } finally {
+            resolverGroup.close();
+        }
+    }
+
+    private static final class ConnectCountingHandler extends AsyncCompletionHandler<Response> {
+
+        private final AtomicInteger connectSuccesses = new AtomicInteger();
+        private final AtomicInteger connectFailures = new AtomicInteger();
+
+        @Override
+        public void onTcpConnectSuccess(InetSocketAddress remoteAddress, Channel connection) {
+            connectSuccesses.incrementAndGet();
+        }
+
+        @Override
+        public void onTcpConnectFailure(InetSocketAddress remoteAddress, Throwable cause) {
+            connectFailures.incrementAndGet();
+        }
+
+        @Override
+        public Response onCompleted(Response response) {
+            return response;
+        }
+    }
+
+    private final class CountingEchoHandler extends AbstractHandler {
+
+        @Override
+        public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response)
+                throws IOException, ServletException {
+            requestsReceived.incrementAndGet();
+            String body = IOUtils.toString(request.getInputStream(), StandardCharsets.UTF_8);
+            if (!body.isEmpty()) {
+                bodiesReceived.incrementAndGet();
+            }
+            response.setStatus(200);
+            response.getOutputStream().write(body.getBytes(StandardCharsets.UTF_8));
+            response.getOutputStream().flush();
+            baseRequest.setHandled(true);
+        }
+    }
+
+    // Hands out the refusing address once, then the live one, so the retry is driven by the resolution
+    // count rather than by timing.
+    private static final class SwitchingResolverGroup extends AddressResolverGroup<InetSocketAddress> {
+
+        private final AtomicInteger resolutions = new AtomicInteger();
+        private final int firstPort;
+        private final int remainingPort;
+
+        SwitchingResolverGroup(int firstPort, int remainingPort) {
+            this.firstPort = firstPort;
+            this.remainingPort = remainingPort;
+        }
+
+        int resolutions() {
+            return resolutions.get();
+        }
+
+        @Override
+        protected AddressResolver<InetSocketAddress> newResolver(EventExecutor executor) {
+            return new AbstractAddressResolver<InetSocketAddress>(executor, InetSocketAddress.class) {
+
+                @Override
+                protected boolean doIsResolved(InetSocketAddress address) {
+                    return !address.isUnresolved();
+                }
+
+                @Override
+                protected void doResolve(InetSocketAddress unresolvedAddress, Promise<InetSocketAddress> promise) {
+                    promise.setSuccess(next());
+                }
+
+                @Override
+                protected void doResolveAll(InetSocketAddress unresolvedAddress, Promise<List<InetSocketAddress>> promise) {
+                    promise.setSuccess(Collections.singletonList(next()));
+                }
+            };
+        }
+
+        private InetSocketAddress next() {
+            int port = resolutions.getAndIncrement() == 0 ? firstPort : remainingPort;
+            return new InetSocketAddress(InetAddress.getLoopbackAddress(), port);
+        }
+    }
+}