RFC6724 destination address ordering + Happy Eyeballs v2 (concurrent multihome dialing).

arturobernalg · arturobernalg · commit f8b92f3cf1a3 · 2025-08-14T15:56:35.000+02:00
Add Rfc6724AddressSelectingDnsResolver; refactor MultihomeIOSessionRequester; wire via ConnectionConfig.
New AsyncClientHappyEyeballs example (URI args, System.out trace) and JUnit tests; Java 8 compatible.
diff --git a/httpclient5/src/test/java/org/apache/hc/client5/http/examples/AsyncClientHappyEyeballs.java b/httpclient5/src/test/java/org/apache/hc/client5/http/examples/AsyncClientHappyEyeballs.java
@@ -26,6 +26,10 @@
  */
 package org.apache.hc.client5.http.examples;
 
+import java.net.URI;
+import java.net.URISyntaxException;
+import java.util.ArrayList;
+import java.util.List;
 import java.util.concurrent.Future;
 
 import org.apache.hc.client5.http.Rfc6724AddressSelectingDnsResolver;
@@ -37,6 +41,7 @@
 import org.apache.hc.client5.http.async.methods.SimpleResponseConsumer;
 import org.apache.hc.client5.http.config.ConnectionConfig;
 import org.apache.hc.client5.http.config.ProtocolFamilyPreference;
+import org.apache.hc.client5.http.config.RequestConfig;
 import org.apache.hc.client5.http.impl.async.CloseableHttpAsyncClient;
 import org.apache.hc.client5.http.impl.async.HttpAsyncClients;
 import org.apache.hc.client5.http.impl.nio.PoolingAsyncClientConnectionManager;
@@ -49,134 +54,114 @@
 import org.apache.hc.core5.http.nio.ssl.TlsStrategy;
 import org.apache.hc.core5.io.CloseMode;
 import org.apache.hc.core5.util.TimeValue;
+import org.apache.hc.core5.util.Timeout;
 
 /**
- * <h2>Example: RFC 6724 DNS ordering + Happy Eyeballs (with logs)</h2>
+ * <h2>Example: RFC 6724 DNS ordering + Happy Eyeballs (with console output)</h2>
  *
- * <p>This example shows how to:
+ * <p>This example shows how to:</p>
  * <ul>
  *   <li>Wrap the system DNS resolver with {@link org.apache.hc.client5.http.Rfc6724AddressSelectingDnsResolver}
- *       to apply <b>RFC 6724</b> destination address selection (v6/v4 ordering).</li>
+ *       to apply <b>RFC 6724</b> destination address selection (IPv6/IPv4 ordering).</li>
  *   <li>Use {@link org.apache.hc.client5.http.config.ConnectionConfig} to enable <b>Happy Eyeballs v2</b> pacing
  *       and set a <b>protocol family preference</b> (e.g., {@code IPV4_ONLY}, {@code IPV6_ONLY}, {@code PREFER_IPV6},
- *       {@code INTERLEAVE}).</li>
- *   <li>Turn on DEBUG logs that make the resolver’s ordering and the connection layer’s decisions observable.</li>
+ *       {@code PREFER_IPV4}, {@code INTERLEAVE}).</li>
+ *   <li>Control the connect timeout so demos don’t stall on slow/broken networks.</li>
  * </ul>
- * </p>
  *
- * <p><b>Logging categories</b> (enable at DEBUG):</p>
- * <ul>
- *   <li>{@code org.apache.hc.client5.http.Rfc6724AddressSelectingDnsResolver} — resolver decisions
- *       (delegate results, RFC 6724 attributes, output order, family bias).</li>
- *   <li>{@code org.apache.hc.client5.http.impl.nio.MultihomeIOSessionRequester} — Happy Eyeballs scheduling and the winning attempt.</li>
- *   <li>(optional) {@code org.apache.hc.client5.http.impl.nio}, {@code org.apache.hc.client5.http.impl.async},
- *       {@code org.apache.hc.core5} — connection pool, protocol exec, TLS, and I/O transport.</li>
- * </ul>
- *
- * <p><b>Log4j2 quick config</b> (trimmed):</p>
- * <pre>{@code
- * <Configuration status="WARN">
- *   <Appenders>
- *     <Console name="Console" target="SYSTEM_OUT">
- *       <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss,SSS} %-5level [%t][%c] %msg%n"/>
- *     </Console>
- *   </Appenders>
- *   <Loggers>
- *     <Logger name="org.apache.hc.client5.http.Rfc6724AddressSelectingDnsResolver" level="debug" additivity="false">
- *       <AppenderRef ref="Console"/>
- *     </Logger>
- *     <Logger name="org.apache.hc.client5.http.impl.nio.MultihomeIOSessionRequester" level="debug" additivity="false">
- *       <AppenderRef ref="Console"/>
- *     </Logger>
- *     <!-- Optional plumbing -->
- *     <Logger name="org.apache.hc.client5.http.impl.nio" level="debug"/>
- *     <Logger name="org.apache.hc.client5.http.impl.async" level="debug"/>
- *     <Logger name="org.apache.hc.core5" level="debug"/>
- *     <Root level="info"><AppenderRef ref="Console"/></Root>
- *   </Loggers>
- * </Configuration>
- * }</pre>
+ * <h3>How to run with the example runner</h3>
+ * <pre>
+ * # Default (no args): hits http://ipv6-test.com/ and https://ipv6-test.com/
+ * ./run-example.sh AsyncClientHappyEyeballs
  *
- * <p><b>What to expect in the logs</b> (trimmed, dual-stack target):</p>
+ * # Pass one URI (runner supports command-line args)
+ * ./run-example.sh AsyncClientHappyEyeballs http://neverssl.com/
  *
- * <p><u>A) {@code IPV4_ONLY}</u> — v6 is present but is filtered out early</p>
- * <pre>{@code
- * ... Rfc6724Resolver resolving host 'ipv6-test.com' via delegate org.apache.hc.client5.http.SystemDefaultDnsResolver
- * ... Rfc6724Resolver familyPreference=IPV4_ONLY
- * ... delegate returned 2 addresses for 'ipv6-test.com': [IPv4(51.75.78.103), IPv6]
- * ... after family filter IPV4_ONLY -> 1 candidate(s): [IPv4(51.75.78.103)]
- * ... RFC6724 output order: [IPv4(51.75.78.103)]
- * ... final ordered list for 'ipv6-test.com': [IPv4(51.75.78.103)]
- * ... using Happy Eyeballs: attemptDelay=250ms, otherFamilyDelay=50ms, pref=IPV4_ONLY
- * ... scheduling connect to IPv4 in 0 ms
- * ... winner: connected to ipv6-test.com/51.75.78.103:80
- * }</pre>
+ * # Pass multiple URIs
+ * ./run-example.sh AsyncClientHappyEyeballs http://neverssl.com/ https://example.org/
  *
- * <p><u>B) {@code PREFER_IPV6}</u> — v6 attempted first, v4 shortly after</p>
- * <pre>{@code
- * ... familyPreference=PREFER_IPV6
- * ... delegate returned 2 addresses: [IPv6(2001:db8::1234), IPv4(203.0.113.10)]
- * ... RFC6724 inferred source addresses: [IPv6(2001:db8::1), IPv4(192.0.2.10)]
- * ... RFC6724 output order: [IPv6(...), IPv4(...)]
- * ... PREFER_IPV6 keeps IPv6 first
- * ... using Happy Eyeballs ... pref=PREFER_IPV6
- * ... scheduling connect to IPv6 in 0 ms, IPv4 in 50 ms
- * ... winner: connected to IPv6(...)
- * }</pre>
+ * # Optional system properties (the runner forwards -D...):
+ * #   -Dhc.he.pref=INTERLEAVE|PREFER_IPV4|PREFER_IPV6|IPV4_ONLY|IPV6_ONLY  (default: INTERLEAVE)
+ * #   -Dhc.he.delay.ms=250        (Happy Eyeballs attempt spacing; default 250)
+ * #   -Dhc.he.other.ms=50         (first other-family offset; default 50; clamped ≤ attempt delay)
+ * #   -Dhc.connect.ms=10000       (TCP connect timeout; default 10000)
  *
- * <p><u>C) {@code INTERLEAVE}</u> — alternate families while honoring RFC-sorted groups</p>
- * <pre>{@code
- * ... familyPreference=INTERLEAVE
- * ... RFC6724 output order: [IPv4(...), IPv6(...), IPv6(...), IPv4(...)]
- * ... INTERLEAVE starting family=IPv4 -> [IPv4(...), IPv6(...), IPv4(...), IPv6(...)]
- * ... final ordered list: [IPv4, IPv6, IPv4, IPv6]
- * ... HEv2 pref=INTERLEAVE; attempts interleaved with 50 ms "other family" offset
- * }</pre>
+ * ./run-example.sh AsyncClientHappyEyeballs http://neverssl.com/ \
+ *   -Dhc.he.pref=INTERLEAVE -Dhc.he.delay.ms=250 -Dhc.he.other.ms=50 -Dhc.connect.ms=8000
+ * </pre>
  *
- * <p><b>Legend (how to read the resolver lines)</b>:</p>
+ * <h3>What to expect</h3>
  * <ul>
- *   <li><code>delegate returned N addresses</code> — raw A/AAAA from the underlying resolver.</li>
- *   <li><code>after family filter ...</code> — hard filter for {@code IPV4_ONLY}/{@code IPV6_ONLY}; no filter for {@code PREFER_*}/{@code INTERLEAVE}.</li>
- *   <li><code>RFC6724 inferred source addresses</code> — UDP DatagramSocket.connect() (no packets) to discover the OS-selected source per destination.</li>
- *   <li><code>candidate dst=... src=... dst[scope=..., prec=..., label=...]</code> — attributes used by RFC 6724 compare:
- *     Rules applied here: 1 (avoid unusable), 2 (scope match), 5 (label match), 6 (precedence), 8 (smaller scope),
- *     9 (longest common prefix for v6). Equal → stable order.</li>
- *   <li><code>output order</code> — RFC 6724 ordering prior to preference reshaping.</li>
- *   <li><code>INTERLEAVE / PREFER_*</code> — final family reshaping before handing to the connection layer.</li>
- *   <li>Happy-Eyeballs lines show pacing (<code>attemptDelay</code>) and first other-family offset
- *     (<code>otherFamilyDelay</code>), plus the eventual <em>winner</em>.</li>
+ *   <li>For dual-stack hosts, the client schedules interleaved IPv6/IPv4 connects per the preference and delays.</li>
+ *   <li>On networks without working IPv6, the IPv6 attempt will likely fail quickly while IPv4 succeeds.</li>
+ *   <li>If you force {@code IPV6_ONLY} on a network without IPv6 routing, you’ll get
+ *       {@code java.net.SocketException: Network is unreachable} — that’s expected.</li>
  * </ul>
  *
- * <p><b>Implementation tip</b>:
- * for the clearest logs, keep the resolver’s bias and the client’s connection preference aligned
- * (e.g., construct {@code new Rfc6724AddressSelectingDnsResolver(SystemDefaultDnsResolver.INSTANCE, pref)}
- * and use the same {@code pref} in {@link org.apache.hc.client5.http.config.ConnectionConfig#setProtocolFamilyPreference}).</p>
- *
- * <p><b>Production note</b>: leave these categories at DEBUG and your root at INFO; enable on demand when diagnosing
- * dual-stack reachability (e.g., broken IPv6 will typically show an inferred source of {@code 0.0.0.0} for the v6 dst,
- * causing RFC 6724 Rule 1 to de-prioritize it).</p>
+ * <h3>Tip</h3>
+ * <p>For the clearest behavior, align the resolver bias and the connection preference:
+ * construct the resolver with the same {@link ProtocolFamilyPreference} that you set in
+ * {@link ConnectionConfig}.</p>
  */
-
 public final class AsyncClientHappyEyeballs {
 
+    private AsyncClientHappyEyeballs() {
+    }
+
     public static void main(final String[] args) throws Exception {
-        // Wrap the system resolver with RFC 6724 destination selection
+        // --- Read settings from system properties (with sensible defaults) ---
+        final ProtocolFamilyPreference pref = parsePref(System.getProperty("hc.he.pref"), ProtocolFamilyPreference.INTERLEAVE);
+        final long attemptDelayMs = parseLong(System.getProperty("hc.he.delay.ms"), 250L);
+        final long otherFamilyDelayMs = Math.min(parseLong(System.getProperty("hc.he.other.ms"), 50L), attemptDelayMs);
+        final long connectMs = parseLong(System.getProperty("hc.connect.ms"), 10000L); // 10s default
+
+        // --- Resolve targets from CLI args (or fall back to ipv6-test.com pair) ---
+        final List<URI> targets = new ArrayList<URI>();
+        if (args != null && args.length > 0) {
+            for (int i = 0; i < args.length; i++) {
+                final URI u = safeParse(args[i]);
+                if (u != null) {
+                    targets.add(u);
+                } else {
+                    System.out.println("Skipping invalid URI: " + args[i]);
+                }
+            }
+        } else {
+            try {
+                targets.add(new URI("http://ipv6-test.com/"));
+                targets.add(new URI("https://ipv6-test.com/"));
+            } catch (final URISyntaxException ignore) {
+            }
+        }
+
+        // --- Print banner so the runner shows the configuration up front ---
+        System.out.println("Happy Eyeballs: pref=" + pref
+                + ", attemptDelay=" + attemptDelayMs + "ms"
+                + ", otherFamilyDelay=" + otherFamilyDelayMs + "ms"
+                + ", connectTimeout=" + connectMs + "ms");
+
+        // --- DNS resolver with RFC 6724 selection (biased using the same pref for clarity) ---
         final Rfc6724AddressSelectingDnsResolver dnsResolver =
-                new Rfc6724AddressSelectingDnsResolver(SystemDefaultDnsResolver.INSTANCE);
+                new Rfc6724AddressSelectingDnsResolver(SystemDefaultDnsResolver.INSTANCE, pref);
 
-        // Enable Happy Eyeballs pacing & family policy via ConnectionConfig
+        // --- Connection config enabling HEv2 pacing and family preference ---
         final ConnectionConfig connectionConfig = ConnectionConfig.custom()
-                .setStaggeredConnectEnabled(true)                                   // off by default
-                .setHappyEyeballsAttemptDelay(TimeValue.ofMilliseconds(250))        // pacing between attempts
-                .setHappyEyeballsOtherFamilyDelay(TimeValue.ofMilliseconds(50))     // delay before first other-family try
-                .setProtocolFamilyPreference(ProtocolFamilyPreference.IPV6_ONLY)   // or PREFER_IPV6 / IPV4_ONLY / etc.
+                .setStaggeredConnectEnabled(true)
+                .setHappyEyeballsAttemptDelay(TimeValue.ofMilliseconds(attemptDelayMs))
+                .setHappyEyeballsOtherFamilyDelay(TimeValue.ofMilliseconds(otherFamilyDelayMs))
+                .setProtocolFamilyPreference(pref).setConnectTimeout(Timeout.ofMilliseconds(connectMs))
+
                 .build();
 
-        // TLS strategy (the builder's build() may be deprecated in your snapshot; it's fine for examples)
+        final RequestConfig requestConfig = RequestConfig.custom()
+                .build();
+
+        // --- TLS strategy (uses system properties for trust/key stores, ALPN, etc.) ---
         final TlsStrategy tls = ClientTlsStrategyBuilder.create()
-                .useSystemProperties().buildAsync();
+                .useSystemProperties()
+                .buildAsync();
 
-        // Connection manager wires in DNS + ConnectionConfig + TLS
+        // --- Connection manager wires in DNS + ConnectionConfig + TLS ---
         final PoolingAsyncClientConnectionManager cm =
                 PoolingAsyncClientConnectionManagerBuilder.create()
                         .setDnsResolver(dnsResolver)
@@ -186,15 +171,24 @@ public static void main(final String[] args) throws Exception {
 
         final CloseableHttpAsyncClient client = HttpAsyncClients.custom()
                 .setConnectionManager(cm)
+                .setDefaultRequestConfig(requestConfig)
                 .build();
 
         client.start();
 
-        final String[] schemes = {URIScheme.HTTP.id, URIScheme.HTTPS.id};
-        for (final String scheme : schemes) {
+        // --- Execute each target once ---
+        for (int i = 0; i < targets.size(); i++) {
+            final URI uri = targets.get(i);
+            final HttpHost host = new HttpHost(
+                    uri.getScheme(),
+                    uri.getHost(),
+                    computePort(uri)
+            );
+            final String path = buildPathAndQuery(uri);
+
             final SimpleHttpRequest request = SimpleRequestBuilder.get()
-                    .setHttpHost(new HttpHost(scheme, "ipv6-test.com"))
-                    .setPath("/")
+                    .setHttpHost(host)
+                    .setPath(path)
                     .build();
 
             System.out.println("Executing request " + request);
@@ -221,13 +215,95 @@ public void cancelled() {
 
             try {
                 future.get();
-            } catch (java.util.concurrent.ExecutionException e) {
-                System.out.println(request + " -> " + e.getCause());
+            } catch (final java.util.concurrent.ExecutionException ex) {
+                // Show the root cause without a giant stack trace in the example
+                System.out.println(request + " -> " + ex.getCause());
             }
         }
 
         System.out.println("Shutting down");
         client.close(CloseMode.GRACEFUL);
         cm.close(CloseMode.GRACEFUL);
     }
+
+    // ------------ helpers (Java 8 friendly) ------------
+
+    private static int computePort(final URI uri) {
+        final int p = uri.getPort();
+        if (p >= 0) {
+            return p;
+        }
+        final String scheme = uri.getScheme();
+        if ("http".equalsIgnoreCase(scheme)) {
+            return 80;
+        }
+        if ("https".equalsIgnoreCase(scheme)) {
+            return 443;
+        }
+        return -1;
+    }
+
+    private static String buildPathAndQuery(final URI uri) {
+        String path = uri.getRawPath();
+        if (path == null || path.isEmpty()) {
+            path = "/";
+        }
+        final String query = uri.getRawQuery();
+        if (query != null && !query.isEmpty()) {
+            return path + "?" + query;
+        }
+        return path;
+    }
+
+    private static long parseLong(final String s, final long defVal) {
+        if (s == null) {
+            return defVal;
+        }
+        try {
+            return Long.parseLong(s.trim());
+        } catch (final NumberFormatException ignore) {
+            return defVal;
+        }
+    }
+
+    private static ProtocolFamilyPreference parsePref(final String s, final ProtocolFamilyPreference defVal) {
+        if (s == null) {
+            return defVal;
+        }
+        final String u = s.trim().toUpperCase(java.util.Locale.ROOT);
+        if ("IPV6_ONLY".equals(u)) {
+            return ProtocolFamilyPreference.IPV6_ONLY;
+        }
+        if ("IPV4_ONLY".equals(u)) {
+            return ProtocolFamilyPreference.IPV4_ONLY;
+        }
+        if ("PREFER_IPV6".equals(u)) {
+            return ProtocolFamilyPreference.PREFER_IPV6;
+        }
+        if ("PREFER_IPV4".equals(u)) {
+            return ProtocolFamilyPreference.PREFER_IPV4;
+        }
+        if ("INTERLEAVE".equals(u)) {
+            return ProtocolFamilyPreference.INTERLEAVE;
+        }
+        return defVal;
+    }
+
+    private static URI safeParse(final String s) {
+        try {
+            final URI u = new URI(s);
+            final String scheme = u.getScheme();
+            if (!URIScheme.HTTP.same(scheme) && !URIScheme.HTTPS.same(scheme)) {
+                System.out.println("Unsupported scheme (only http/https): " + s);
+                return null;
+            }
+            if (u.getHost() == null) {
+                System.out.println("Missing host in URI: " + s);
+                return null;
+            }
+            return u;
+        } catch (final URISyntaxException ex) {
+            return null;
+        }
+    }
 }
diff --git a/httpclient5/src/test/resources/log4j2.xml b/httpclient5/src/test/resources/log4j2.xml
@@ -15,23 +15,15 @@
  See the License for the specific language governing permissions and
  limitations under the License.
 -->
-<Configuration status="WARN">
+<Configuration status="WARN" name="XMLConfigTest">
   <Appenders>
-    <Console name="Console" target="SYSTEM_OUT">
-      <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss,SSS} %-5level [%t][%c] %msg%n"/>
+    <Console name="STDOUT">
+      <PatternLayout pattern="%d %-5level [%t][%logger]%notEmpty{[%markerSimpleName]} %msg%n%xThrowable" />
     </Console>
   </Appenders>
   <Loggers>
-    <!-- Happy Eyeballs scheduler + decisions -->
-    <Logger name="org.apache.hc.client5.http.impl.nio.MultihomeIOSessionRequester" level="debug" additivity="false">
-      <AppenderRef ref="Console"/>
-    </Logger>
-    <!-- Optional: connection manager + operator -->
-    <Logger name="org.apache.hc.client5.http.impl.nio" level="debug"/>
-    <Logger name="org.apache.hc.client5.http.impl.async" level="debug"/>
-    <Logger name="org.apache.hc.core5" level="debug"/>
-    <Root level="info">
-      <AppenderRef ref="Console"/>
+    <Root level="FATAL">
+      <AppenderRef ref="STDOUT" />
     </Root>
   </Loggers>
 </Configuration>
