Resolve A/AAAA address families independently via AsyncDnsResolver

httpclient5/src/main/java/org/apache/hc/client5/http/AsyncDnsResolver.java

@@ -0,0 +1,69 @@
+/*
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+package org.apache.hc.client5.http;
+
+import org.apache.hc.core5.annotation.Experimental;
+import org.apache.hc.core5.concurrent.Cancellable;
+
+/**
+ * Optional DNS resolver SPI capable of resolving a host's address families (A / AAAA)
+ * independently and asynchronously, reporting each family's result to
+ * {@link DnsResolutionCallback} as soon as it becomes available rather than blocking
+ * until every family has been queried (RFC 8305, Section 3).
+ *
+ * <p>This is a strictly optional extension of {@link DnsResolver}: when none is
+ * configured, resolution falls back to the plain, synchronous {@link DnsResolver},
+ * which remains the primary resolution SPI. {@link DnsResolver} cannot itself
+ * implement this interface by running its blocking lookup on a separate thread:
+ * that would still serialize both families behind one blocking call and misrepresent
+ * it as an independent asynchronous resolution of each. Implement this interface only
+ * when the underlying resolution mechanism genuinely queries A and AAAA records
+ * independently, for example an asynchronous DNS client.</p>
+ *
+ * <p>This SPI is considered experimental and may be discontinued in the future.</p>
+ *
+ * @since 5.7
+ */
+@Experimental
+public interface AsyncDnsResolver {
+
+    /**
+     * Starts resolving {@code host}. Implementations call {@link DnsResolutionCallback#resolved}
+     * once for each address family that resolves successfully, as soon as that family's
+     * result becomes available, independently of any other family still outstanding, and
+     * call {@link DnsResolutionCallback#failed} once for each family that fails or does not
+     * apply. Once every attempted family has either resolved or failed, implementations call
+     * {@link DnsResolutionCallback#completed()} exactly once.
+     *
+     * @param host the host name to resolve.
+     * @param port the port to attach to resolved addresses.
+     * @param callback receives each family's result as it becomes available.
+     * @return a handle that cancels any outstanding queries.
+     */
+    Cancellable resolve(String host, int port, DnsResolutionCallback callback);
+
+}

httpclient5/src/main/java/org/apache/hc/client5/http/DnsResolutionCallback.java

@@ -0,0 +1,71 @@
+/*
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+package org.apache.hc.client5.http;
+
+import java.net.InetSocketAddress;
+import java.util.List;
+
+import org.apache.hc.core5.annotation.Experimental;
+
+/**
+ * Receives the results of an {@link AsyncDnsResolver} resolution, one address family
+ * at a time, as each becomes available.
+ *
+ * <p>This SPI is considered experimental and may be discontinued in the future.</p>
+ *
+ * @since 5.7
+ */
+@Experimental
+public interface DnsResolutionCallback {
+
+    /**
+     * Called once a single address family (A or AAAA) has resolved successfully, as soon
+     * as that family's result is available and independently of any other family still
+     * being resolved. May be called more than once for the same resolution, once per
+     * family that resolves successfully; never called with an empty or {@code null} list.
+     *
+     * @param addresses the addresses resolved for one address family.
+     */
+    void resolved(List<InetSocketAddress> addresses);
+
+    /**
+     * Called once a single address family has failed to resolve or does not apply to
+     * the target host. May be called more than once, once per family that fails,
+     * including after {@link #resolved(List)} has already provided addresses for a
+     * different family.
+     *
+     * @param cause the reason this family could not be resolved.
+     */
+    void failed(Exception cause);
+
+    /**
+     * Called exactly once, after every attempted address family has either resolved
+     * or failed, to signal that no further results will arrive for this resolution.
+     */
+    void completed();
+
+}

httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/DefaultAsyncClientConnectionOperator.java

@@ -34,6 +34,7 @@
 import java.nio.file.Path;
 import java.util.concurrent.Future;
 
+import org.apache.hc.client5.http.AsyncDnsResolver;
 import org.apache.hc.client5.http.DnsResolver;
 import org.apache.hc.client5.http.SchemePortResolver;
 import org.apache.hc.client5.http.UnsupportedSchemeException;
@@ -96,9 +97,22 @@ protected DefaultAsyncClientConnectionOperator(
             final DnsResolver dnsResolver,
             final boolean happyEyeballsEnabled,
             final TimeValue connectionAttemptDelay) {
+        this(tlsStrategyLookup, schemePortResolver, dnsResolver, happyEyeballsEnabled, connectionAttemptDelay, null);
+    }
+
+    /**
+     * @since 5.7
+     */
+    protected DefaultAsyncClientConnectionOperator(
+            final Lookup<TlsStrategy> tlsStrategyLookup,
+            final SchemePortResolver schemePortResolver,
+            final DnsResolver dnsResolver,
+            final boolean happyEyeballsEnabled,
+            final TimeValue connectionAttemptDelay,
+            final AsyncDnsResolver asyncDnsResolver) {
         this.tlsStrategyLookup = Args.notNull(tlsStrategyLookup, "TLS strategy lookup");
         this.schemePortResolver = schemePortResolver != null ? schemePortResolver : DefaultSchemePortResolver.INSTANCE;
-        this.sessionRequester = new MultihomeIOSessionRequester(dnsResolver, happyEyeballsEnabled, connectionAttemptDelay);
+        this.sessionRequester = new MultihomeIOSessionRequester(dnsResolver, happyEyeballsEnabled, connectionAttemptDelay, asyncDnsResolver);
     }
 
     @Override

httpclient5/src/main/java/org/apache/hc/client5/http/impl/nio/MultihomeConnectionInitiator.java

@@ -30,6 +30,7 @@
 import java.net.SocketAddress;
 import java.util.concurrent.Future;
 
+import org.apache.hc.client5.http.AsyncDnsResolver;
 import org.apache.hc.client5.http.DnsResolver;
 import org.apache.hc.core5.annotation.Contract;
 import org.apache.hc.core5.annotation.ThreadingBehavior;
@@ -89,6 +90,35 @@ public MultihomeConnectionInitiator(
         this.sessionRequester = new MultihomeIOSessionRequester(dnsResolver, happyEyeballsEnabled, connectionAttemptDelay);
     }
 
+    /**
+     * Creates a multi-home connection initiator that, when {@code happyEyeballsEnabled} is
+     * {@code true} and {@code asyncDnsResolver} is not {@code null}, resolves each address
+     * family (A / AAAA) independently through {@code asyncDnsResolver} and races connection
+     * attempts against each family's addresses as soon as that family resolves (RFC 8305,
+     * Sections 3 and 8), rather than waiting for {@code dnsResolver} to resolve every family
+     * behind one blocking call. When {@code asyncDnsResolver} is {@code null}, behavior is
+     * identical to {@link #MultihomeConnectionInitiator(ConnectionInitiator, DnsResolver, boolean, TimeValue)}.
+     *
+     * @param connectionInitiator the connection initiator.
+     * @param dnsResolver the DNS resolver to use when {@code asyncDnsResolver} is {@code null}.
+     * @param happyEyeballsEnabled whether to race connection attempts instead of trying them
+     *                             sequentially.
+     * @param connectionAttemptDelay delay between the start of successive connection attempts;
+     *                               see {@link #MultihomeConnectionInitiator(ConnectionInitiator, DnsResolver, boolean, TimeValue)}.
+     * @param asyncDnsResolver optional resolver capable of resolving address families
+     *                         independently and asynchronously; may be {@code null}.
+     * @since 5.7
+     */
+    public MultihomeConnectionInitiator(
+            final ConnectionInitiator connectionInitiator,
+            final DnsResolver dnsResolver,
+            final boolean happyEyeballsEnabled,
+            final TimeValue connectionAttemptDelay,
+            final AsyncDnsResolver asyncDnsResolver) {
+        this.connectionInitiator = Args.notNull(connectionInitiator, "Connection initiator");
+        this.sessionRequester = new MultihomeIOSessionRequester(dnsResolver, happyEyeballsEnabled, connectionAttemptDelay, asyncDnsResolver);
+    }
+
     @Override
     public Future<IOSession> connect(
             final NamedEndpoint remoteEndpoint,