diff --git a/httpclient5-testing/src/test/java/org/apache/hc/client5/testing/ManualRfc6724ResolverIT.java b/httpclient5-testing/src/test/java/org/apache/hc/client5/testing/ManualRfc6724ResolverIT.java new file mode 100644 index 0000000000..7503e8c12e --- /dev/null +++ b/httpclient5-testing/src/test/java/org/apache/hc/client5/testing/ManualRfc6724ResolverIT.java @@ -0,0 +1,87 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +package org.apache.hc.client5.testing; + +import static org.junit.jupiter.api.Assumptions.assumeTrue; + +import java.net.Inet6Address; +import java.net.InetAddress; + +import org.apache.hc.client5.http.DnsResolver; +import org.apache.hc.client5.http.Rfc6724AddressSelectingDnsResolver; +import org.apache.hc.client5.http.SystemDefaultDnsResolver; +import org.apache.hc.client5.http.config.ProtocolFamilyPreference; +import org.junit.jupiter.api.Test; + +class ManualRfc6724ResolverIT { + + private static final String PROP_ENABLE = "httpclient.rfc6724.it"; + private static final String PROP_HOST = "httpclient.rfc6724.host"; + + @Test + void resolve_and_dump_order() throws Exception { + assumeTrue(Boolean.getBoolean(PROP_ENABLE), + "Enable with -Dhttpclient.rfc6724.it=true"); + + final String host = System.getProperty(PROP_HOST, "localhost"); + + final DnsResolver base = SystemDefaultDnsResolver.INSTANCE; + + System.out.println("Host: " + host); + + dump(base, host, ProtocolFamilyPreference.DEFAULT); + System.out.println(); + dump(base, host, ProtocolFamilyPreference.INTERLEAVE); + } + + private static void dump( + final DnsResolver base, + final String host, + final ProtocolFamilyPreference pref) throws Exception { + + final Rfc6724AddressSelectingDnsResolver resolver = + new Rfc6724AddressSelectingDnsResolver(base, pref); + + final InetAddress[] out = resolver.resolve(host); + + int v4 = 0; + int v6 = 0; + + System.out.println("Preference: " + pref); + for (final InetAddress a : out) { + if (a instanceof Inet6Address) { + v6++; + System.out.println(" IPv6 " + a.getHostAddress()); + } else { + v4++; + System.out.println(" IPv4 " + a.getHostAddress()); + } + } + System.out.println("Counts: IPv4=" + v4 + " IPv6=" + v6); + } +} diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/Rfc6724AddressSelectingDnsResolver.java b/httpclient5/src/main/java/org/apache/hc/client5/http/Rfc6724AddressSelectingDnsResolver.java new file mode 100644 index 0000000000..48f0e061f7 --- /dev/null +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/Rfc6724AddressSelectingDnsResolver.java @@ -0,0 +1,670 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +package org.apache.hc.client5.http; + +import java.net.DatagramSocket; +import java.net.Inet4Address; +import java.net.Inet6Address; +import java.net.InetAddress; +import java.net.InetSocketAddress; +import java.net.SocketException; +import java.net.UnknownHostException; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collections; +import java.util.Comparator; +import java.util.List; +import java.util.Objects; +import java.util.stream.Collectors; + +import org.apache.hc.client5.http.config.ProtocolFamilyPreference; +import org.apache.hc.core5.annotation.Contract; +import org.apache.hc.core5.annotation.ThreadingBehavior; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +/** + * {@code Rfc6724AddressSelectingDnsResolver} wraps a delegate {@link DnsResolver} + * and applies RFC 6724 destination address selection rules (RFC 6724 §6) + * to the returned addresses. It can also enforce or bias a protocol family preference. + * + *

The canonical hostname lookup is delegated unchanged.

+ * + *

+ * {@link ProtocolFamilyPreference#DEFAULT} keeps the RFC 6724 sorted order intact (no family bias). + * {@link ProtocolFamilyPreference#INTERLEAVE} interleaves IPv6 and IPv4 addresses (v6, v4, v6, …), + * preserving the relative order within each family as produced by RFC 6724 sorting. + *

+ * + * @since 5.7 + */ +@Contract(threading = ThreadingBehavior.IMMUTABLE) +public final class Rfc6724AddressSelectingDnsResolver implements DnsResolver { + + private static final Logger LOG = LoggerFactory.getLogger(Rfc6724AddressSelectingDnsResolver.class); + + private static final int PROBE_PORT = 53; // UDP connect trick; no packets sent + + @FunctionalInterface + interface SourceAddressResolver { + InetAddress resolveSource(final InetSocketAddress destination) throws SocketException; + } + + private static final SourceAddressResolver DEFAULT_SOURCE_ADDRESS_RESOLVER = destination -> { + try (final DatagramSocket socket = new DatagramSocket()) { + socket.connect(destination); + return socket.getLocalAddress(); + } + }; + + private final DnsResolver delegate; + private final ProtocolFamilyPreference familyPreference; + private final SourceAddressResolver sourceAddressResolver; + + /** + * Creates a new resolver that applies RFC 6724 ordering with no family bias (DEFAULT). + * + * @param delegate underlying resolver to use. + */ + public Rfc6724AddressSelectingDnsResolver(final DnsResolver delegate) { + this(delegate, ProtocolFamilyPreference.DEFAULT); + } + + /** + * Creates a new resolver that applies RFC 6724 ordering and a specific protocol family preference. + * + * @param delegate underlying resolver to use. + * @param familyPreference family preference to apply (e.g. PREFER_IPV6, IPV4_ONLY). + */ + public Rfc6724AddressSelectingDnsResolver( + final DnsResolver delegate, + final ProtocolFamilyPreference familyPreference) { + this(delegate, familyPreference, DEFAULT_SOURCE_ADDRESS_RESOLVER); + } + + // Package-private for unit tests: allows deterministic source address inference. + Rfc6724AddressSelectingDnsResolver( + final DnsResolver delegate, + final ProtocolFamilyPreference familyPreference, + final SourceAddressResolver sourceAddressResolver) { + this.delegate = Objects.requireNonNull(delegate, "delegate"); + this.familyPreference = familyPreference != null ? familyPreference : ProtocolFamilyPreference.DEFAULT; + this.sourceAddressResolver = sourceAddressResolver != null ? sourceAddressResolver : DEFAULT_SOURCE_ADDRESS_RESOLVER; + } + + @Override + public InetAddress[] resolve(final String host) throws UnknownHostException { + final InetAddress[] resolved = delegate.resolve(host); + + if (resolved == null) { + if (LOG.isDebugEnabled()) { + LOG.debug("{} resolved '{}' -> null", simpleName(), host); + } + return null; + } + + if (resolved.length <= 1) { + if (LOG.isDebugEnabled()) { + LOG.debug("{} resolved '{}' -> {}", simpleName(), host, fmt(resolved)); + } + return resolved; + } + + if (LOG.isTraceEnabled()) { + LOG.trace("{} resolving host '{}' via delegate {}", simpleName(), host, delegate.getClass().getName()); + LOG.trace("{} familyPreference={}", simpleName(), familyPreference); + LOG.trace("{} delegate returned {} addresses for '{}': {}", simpleName(), resolved.length, host, fmt(resolved)); + } + + final List candidates = filterCandidates(resolved, familyPreference); + + if (candidates.isEmpty()) { + if (LOG.isDebugEnabled()) { + LOG.debug("{} resolved '{}' -> []", simpleName(), host); + } + return new InetAddress[0]; + } + + final List rfcSorted = sortByRfc6724(candidates); + final List ordered = applyFamilyPreference(rfcSorted, familyPreference); + + if (LOG.isDebugEnabled()) { + LOG.debug("{} resolved '{}' -> {}", simpleName(), host, fmt(ordered)); + } + + return ordered.toArray(new InetAddress[0]); + } + + @Override + public String resolveCanonicalHostname(final String host) throws UnknownHostException { + if (LOG.isTraceEnabled()) { + LOG.trace("{} resolveCanonicalHostname('{}') via delegate {}", simpleName(), host, delegate.getClass().getName()); + } + return delegate.resolveCanonicalHostname(host); + } + + private static boolean isUsableDestination(final InetAddress ip) { + if (ip == null) { + return false; + } + if (ip.isAnyLocalAddress()) { + return false; + } + // HTTP/TCP is for unicast destinations; multicast is not a valid connect target. + if (ip.isMulticastAddress()) { + return false; + } + return true; + } + + private static List filterCandidates( + final InetAddress[] resolved, + final ProtocolFamilyPreference pref) { + + final List out = new ArrayList<>(resolved.length); + for (final InetAddress a : resolved) { + if (!isUsableDestination(a)) { + continue; + } + switch (pref) { + case IPV4_ONLY: { + if (a instanceof Inet4Address) { + out.add(a); + } + break; + } + case IPV6_ONLY: { + if (a instanceof Inet6Address) { + out.add(a); + } + break; + } + default: { + out.add(a); + break; + } + } + } + return out; + } + + // --- RFC 6724 helpers --- + + private List sortByRfc6724(final List addrs) { + if (addrs.size() < 2) { + return addrs; + } + + if (LOG.isTraceEnabled()) { + LOG.trace("RFC6724 input candidates: {}", fmt(addrs)); + } + + final List socketAddresses = new ArrayList<>(addrs.size()); + for (final InetAddress a : addrs) { + socketAddresses.add(new InetSocketAddress(a, PROBE_PORT)); + } + + final List srcs = inferSourceAddresses(socketAddresses); + + final List infos = new ArrayList<>(addrs.size()); + for (int i = 0; i < addrs.size(); i++) { + final InetAddress dst = addrs.get(i); + final InetAddress src = srcs.get(i); + infos.add(new Info(dst, src, ipAttrOf(dst), ipAttrOf(src))); + } + + if (LOG.isTraceEnabled()) { + for (final Info info : infos) { + LOG.trace("RFC6724 candidate dst={} src={} dst[scope={},prec={},label={}] src[scope={},prec={},label={}]", + addr(info.dst), addr(info.src), + info.dstAttr.scope, info.dstAttr.precedence, info.dstAttr.label, + info.srcAttr.scope, info.srcAttr.precedence, info.srcAttr.label); + } + } + + infos.sort(RFC6724_COMPARATOR); + + final List out = new ArrayList<>(infos.size()); + for (final Info info : infos) { + out.add(info.dst); + } + + if (LOG.isTraceEnabled()) { + LOG.trace("RFC6724 output order: {}", fmt(out)); + } + + return out; + } + + private List inferSourceAddresses(final List destinations) { + final List srcs = new ArrayList<>(destinations.size()); + + for (final InetSocketAddress dest : destinations) { + InetAddress src = null; + try { + src = sourceAddressResolver.resolveSource(dest); + } catch (final SocketException ignore) { + if (LOG.isTraceEnabled()) { + LOG.trace("RFC6724 could not infer source address for {}: {}", dest, ignore.toString()); + } + } + srcs.add(src); + } + + if (LOG.isTraceEnabled()) { + final List printable = new ArrayList<>(srcs.size()); + for (final InetAddress a : srcs) { + printable.add(addr(a)); + } + LOG.trace("RFC6724 inferred source addresses: {}", printable); + } + + return srcs; + } + + private static List applyFamilyPreference( + final List rfcSorted, + final ProtocolFamilyPreference pref) { + + if (rfcSorted.size() <= 1) { + return rfcSorted; + } + + switch (pref) { + case PREFER_IPV6: + case PREFER_IPV4: { + final boolean preferV6 = pref == ProtocolFamilyPreference.PREFER_IPV6; + + // Stable: preserves the RFC6724 order within each family. + final List out = rfcSorted.stream() + .sorted(Comparator.comparingInt(a -> ((a instanceof Inet6Address) == preferV6) ? 0 : 1)) + .collect(Collectors.toList()); + + if (LOG.isTraceEnabled()) { + LOG.trace("Family preference {} applied. Output: {}", pref, fmt(out)); + } + return out; + } + case INTERLEAVE: { + final List out = interleaveFamilies(rfcSorted); + if (LOG.isTraceEnabled()) { + LOG.trace("Family preference {} applied. Output: {}", pref, fmt(out)); + } + return out; + } + case IPV4_ONLY: + case IPV6_ONLY: { + // already filtered earlier + return rfcSorted; + } + case DEFAULT: + default: { + // No family bias. Keep RFC 6724 order intact. + return rfcSorted; + } + } + } + + private static List interleaveFamilies(final List rfcSorted) { + final List v6 = new ArrayList<>(); + final List v4 = new ArrayList<>(); + + for (final InetAddress a : rfcSorted) { + if (a instanceof Inet6Address) { + v6.add(a); + } else { + v4.add(a); + } + } + + if (v6.isEmpty() || v4.isEmpty()) { + return rfcSorted; + } + + final boolean startWithV6 = rfcSorted.get(0) instanceof Inet6Address; + final List first = startWithV6 ? v6 : v4; + final List second = startWithV6 ? v4 : v6; + + final List out = new ArrayList<>(rfcSorted.size()); + int i = 0; + int j = 0; + while (i < first.size() || j < second.size()) { + if (i < first.size()) { + out.add(first.get(i++)); + } + if (j < second.size()) { + out.add(second.get(j++)); + } + } + return out; + } + + // --- RFC 6724 score structs --- + + private static final class Info { + final InetAddress dst; + final InetAddress src; + final Attr dstAttr; + final Attr srcAttr; + + Info(final InetAddress dst, final InetAddress src, final Attr dstAttr, final Attr srcAttr) { + this.dst = dst; + this.src = src; + this.dstAttr = dstAttr; + this.srcAttr = srcAttr; + } + } + + private static final class Attr { + final Scope scope; + final int precedence; + final int label; + + Attr(final Scope scope, final int precedence, final int label) { + this.scope = scope; + this.precedence = precedence; + this.label = label; + } + } + + private enum Scope { + INTERFACE_LOCAL(0x1), + LINK_LOCAL(0x2), + ADMIN_LOCAL(0x4), + SITE_LOCAL(0x5), + ORG_LOCAL(0x8), + GLOBAL(0xe); + + final int value; + + Scope(final int v) { + this.value = v; + } + + static Scope fromValue(final int v) { + switch (v) { + case 0x1: { + return INTERFACE_LOCAL; + } + case 0x2: { + return LINK_LOCAL; + } + case 0x4: { + return ADMIN_LOCAL; + } + case 0x5: { + return SITE_LOCAL; + } + case 0x8: { + return ORG_LOCAL; + } + default: { + return GLOBAL; + } + } + } + } + + private static Attr ipAttrOf(final InetAddress ip) { + if (ip == null) { + return new Attr(Scope.GLOBAL, 0, 0); + } + final PolicyEntry e = classify(ip); + return new Attr(classifyScope(ip), e.precedence, e.label); + } + + private static Scope classifyScope(final InetAddress ip) { + if (ip.isLoopbackAddress()) { + return Scope.INTERFACE_LOCAL; + } + if (ip.isLinkLocalAddress()) { + return Scope.LINK_LOCAL; + } + if (ip.isMulticastAddress()) { + if (ip instanceof Inet6Address) { + // RFC 6724 §3.1 and RFC 4291: low 4 bits of second byte are scope for IPv6 multicast. + return Scope.fromValue(ip.getAddress()[1] & 0x0f); + } + return Scope.GLOBAL; + } + if (ip.isSiteLocalAddress()) { + return Scope.SITE_LOCAL; + } + return Scope.GLOBAL; + } + + private static final class PolicyEntry { + final Network prefix; + final int precedence; + final int label; + + PolicyEntry(final Network prefix, final int precedence, final int label) { + this.prefix = prefix; + this.precedence = precedence; + this.label = label; + } + } + + private static final class Network { + final byte[] ip; + final int bits; + + Network(final byte[] ip, final int bits) { + this.ip = ip; + this.bits = bits; + } + + boolean contains(final InetAddress addr) { + final byte[] a = addr instanceof Inet4Address ? v4toMapped(addr.getAddress()) : addr.getAddress(); + if (a.length != ip.length) { + return false; + } + final int fullBytes = bits / 8; + for (int i = 0; i < fullBytes; i++) { + if (a[i] != ip[i]) { + return false; + } + } + final int rem = bits % 8; + if (rem == 0) { + return true; + } + final int mask = 0xff << (8 - rem); + final int aByte = a[fullBytes] & 0xff; + final int ipByte = ip[fullBytes] & 0xff; + return (aByte & mask) == (ipByte & mask); + } + + private static byte[] v4toMapped(final byte[] v4) { + final byte[] mapped = new byte[16]; + mapped[10] = (byte) 0xff; + mapped[11] = (byte) 0xff; + System.arraycopy(v4, 0, mapped, 12, 4); + return mapped; + } + } + + private static Network toPrefix(final String text, final int bits) { + try { + return new Network(InetAddress.getByName(text).getAddress(), bits); + } catch (final UnknownHostException ex) { + throw new IllegalArgumentException(ex); + } + } + + private static final List POLICY_TABLE = + Collections.unmodifiableList(Arrays.asList( + new PolicyEntry(toPrefix("::1", 128), 50, 0), + new PolicyEntry(toPrefix("::ffff:0:0", 96), 35, 4), + new PolicyEntry(toPrefix("::", 96), 1, 3), + new PolicyEntry(toPrefix("2001::", 32), 5, 5), + new PolicyEntry(toPrefix("2002::", 16), 30, 2), + new PolicyEntry(toPrefix("3ffe::", 16), 1, 12), + new PolicyEntry(toPrefix("fec0::", 10), 1, 11), + new PolicyEntry(toPrefix("fc00::", 7), 3, 13), + new PolicyEntry(toPrefix("::", 0), 40, 1) + )); + + private static PolicyEntry classify(final InetAddress ip) { + for (final PolicyEntry e : POLICY_TABLE) { + if (e.prefix.contains(ip)) { + return e; + } + } + return new PolicyEntry(null, 40, 1); + } + + private static final Comparator RFC6724_COMPARATOR = (a, b) -> { + final InetAddress aDst = a.dst; + final InetAddress bDst = b.dst; + final InetAddress aSrc = a.src; + final InetAddress bSrc = b.src; + final Attr aDstAttr = a.dstAttr; + final Attr bDstAttr = b.dstAttr; + final Attr aSrcAttr = a.srcAttr; + final Attr bSrcAttr = b.srcAttr; + + final int preferA = -1; + final int preferB = 1; + + // RFC 6724 §6: destination address selection rules. + + // Rule 1: Avoid unusable destinations. + final boolean validA = aSrc != null && !aSrc.isAnyLocalAddress(); + final boolean validB = bSrc != null && !bSrc.isAnyLocalAddress(); + if (!validA && !validB) { + return 0; + } + if (!validB) { + return preferA; + } + if (!validA) { + return preferB; + } + + // Rule 2: Prefer matching scope. + if (aDstAttr.scope == aSrcAttr.scope && bDstAttr.scope != bSrcAttr.scope) { + return preferA; + } + if (aDstAttr.scope != aSrcAttr.scope && bDstAttr.scope == bSrcAttr.scope) { + return preferB; + } + + // Rule 5: Prefer matching label. + if (aSrcAttr.label == aDstAttr.label && bSrcAttr.label != bDstAttr.label) { + return preferA; + } + if (aSrcAttr.label != aDstAttr.label && bSrcAttr.label == bDstAttr.label) { + return preferB; + } + + // Rule 6: Prefer higher precedence. + if (aDstAttr.precedence > bDstAttr.precedence) { + return preferA; + } + if (aDstAttr.precedence < bDstAttr.precedence) { + return preferB; + } + + // Rule 8: Prefer smaller scope. + if (aDstAttr.scope.value < bDstAttr.scope.value) { + return preferA; + } + if (aDstAttr.scope.value > bDstAttr.scope.value) { + return preferB; + } + + // Rule 9: Longest matching prefix (IPv6 only). + if (aDst instanceof Inet6Address && bDst instanceof Inet6Address) { + final int commonA = commonPrefixLen(aSrc, aDst); + final int commonB = commonPrefixLen(bSrc, bDst); + if (commonA > commonB) { + return preferA; + } + if (commonA < commonB) { + return preferB; + } + } + + // Rule 10: Otherwise equal (original order preserved by stable sort). + return 0; + }; + + private static int commonPrefixLen(final InetAddress a, final InetAddress b) { + if (a == null || b == null || a.getClass() != b.getClass()) { + return 0; + } + final byte[] aa = a.getAddress(); + final byte[] bb = b.getAddress(); + final int len = Math.min(aa.length, bb.length); + int bits = 0; + for (int i = 0; i < len; i++) { + final int x = (aa[i] ^ bb[i]) & 0xFF; + if (x == 0) { + bits += 8; + } else { + for (int j = 7; j >= 0; j--) { + if ((x & (1 << j)) != 0) { + return bits; + } + bits++; + } + return bits; + } + } + return bits; + } + + private static String addr(final InetAddress a) { + if (a == null) { + return "null"; + } + final String family = a instanceof Inet6Address ? "IPv6" : "IPv4"; + return family + "(" + a.getHostAddress() + ")"; + } + + private static List fmt(final InetAddress[] arr) { + final List out = new ArrayList<>(arr.length); + for (final InetAddress a : arr) { + out.add(addr(a)); + } + return out; + } + + private static List fmt(final List arr) { + final List out = new ArrayList<>(arr.size()); + for (final InetAddress a : arr) { + out.add(addr(a)); + } + return out; + } + + private static String simpleName() { + return "Rfc6724Resolver"; + } +} diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/config/ProtocolFamilyPreference.java b/httpclient5/src/main/java/org/apache/hc/client5/http/config/ProtocolFamilyPreference.java new file mode 100644 index 0000000000..7ad272e3f6 --- /dev/null +++ b/httpclient5/src/main/java/org/apache/hc/client5/http/config/ProtocolFamilyPreference.java @@ -0,0 +1,72 @@ +/* + * ==================================================================== + * 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 + * . + * + */ +package org.apache.hc.client5.http.config; + +/** + * Protocol family preference for outbound connections. + * + *

Used by connection initiation code to filter or order destination + * addresses and, when enabled, to interleave families during staggered attempts. + * + * @since 5.7 + */ +public enum ProtocolFamilyPreference { + + /** + * No family bias. Preserve RFC 6724 order. + */ + DEFAULT, + + /** + * Prefer IPv4 addresses (stable: preserves RFC order within each family). + */ + PREFER_IPV4, + + /** + * Prefer IPv6 addresses (stable: preserves RFC order within each family). + */ + PREFER_IPV6, + + /** + * Filter out all non-IPv4 addresses. + */ + IPV4_ONLY, + + /** + * Filter out all non-IPv6 addresses. + */ + IPV6_ONLY, + + /** + * Interleave address families (v6, then v4, then v6, …) when multiple + * addresses are available, preserving the relative order within each family + * as produced by RFC 6724 sorting. + */ + INTERLEAVE + +} + diff --git a/httpclient5/src/test/java/org/apache/hc/client5/http/Rfc6724AddressSelectingDnsResolverTest.java b/httpclient5/src/test/java/org/apache/hc/client5/http/Rfc6724AddressSelectingDnsResolverTest.java new file mode 100644 index 0000000000..3690a99aeb --- /dev/null +++ b/httpclient5/src/test/java/org/apache/hc/client5/http/Rfc6724AddressSelectingDnsResolverTest.java @@ -0,0 +1,385 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +package org.apache.hc.client5.http; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNotNull; + +import java.lang.reflect.Method; +import java.net.Inet4Address; +import java.net.Inet6Address; +import java.net.InetAddress; +import java.net.InetSocketAddress; +import java.net.UnknownHostException; +import java.util.Arrays; +import java.util.List; + +import org.apache.hc.client5.http.config.ProtocolFamilyPreference; +import org.apache.hc.client5.http.impl.InMemoryDnsResolver; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +class Rfc6724AddressSelectingDnsResolverTest { + + private static final Rfc6724AddressSelectingDnsResolver.SourceAddressResolver NO_SOURCE_ADDR = + (final InetSocketAddress dest) -> null; + + private InMemoryDnsResolver delegate; + + @BeforeEach + void setUp() { + delegate = new InMemoryDnsResolver(); + } + + @Test + void ipv4Only_filtersOutIPv6() throws Exception { + final InetAddress v4 = inet("203.0.113.10"); // TEST-NET-3 + final InetAddress v6 = inet("2001:db8::10"); // documentation prefix + + delegate.add("dual.example", v6, v4); + + final Rfc6724AddressSelectingDnsResolver r = + new Rfc6724AddressSelectingDnsResolver(delegate, ProtocolFamilyPreference.IPV4_ONLY, NO_SOURCE_ADDR); + + final InetAddress[] ordered = r.resolve("dual.example"); + assertEquals(1, ordered.length); + assertInstanceOf(Inet4Address.class, ordered[0]); + assertEquals(v4, ordered[0]); + } + + @Test + void ipv6Only_filtersOutIPv4() throws Exception { + final InetAddress v4 = inet("192.0.2.1"); // TEST-NET-1 + final InetAddress v6 = inet("2001:db8::1"); + + delegate.add("dual.example", v4, v6); + + final Rfc6724AddressSelectingDnsResolver r = + new Rfc6724AddressSelectingDnsResolver(delegate, ProtocolFamilyPreference.IPV6_ONLY, NO_SOURCE_ADDR); + + final InetAddress[] ordered = r.resolve("dual.example"); + assertEquals(1, ordered.length); + assertInstanceOf(Inet6Address.class, ordered[0]); + assertEquals(v6, ordered[0]); + } + + @Test + void ipv4Only_emptyWhenNoIPv4Candidates() throws Exception { + final InetAddress v6a = inet("2001:db8::1"); + final InetAddress v6b = inet("2001:db8::2"); + + delegate.add("v6only.example", v6a, v6b); + + final Rfc6724AddressSelectingDnsResolver r = + new Rfc6724AddressSelectingDnsResolver(delegate, ProtocolFamilyPreference.IPV4_ONLY, NO_SOURCE_ADDR); + + final InetAddress[] ordered = r.resolve("v6only.example"); + assertEquals(0, ordered.length); + } + + @Test + void default_hasNoFamilyBias() throws Exception { + final InetAddress v6a = inet("2001:db8::1"); + final InetAddress v6b = inet("2001:db8::2"); + final InetAddress v4a = inet("192.0.2.1"); + final InetAddress v4b = inet("203.0.113.10"); + + delegate.add("dual.example", v6a, v6b, v4a, v4b); + + final Rfc6724AddressSelectingDnsResolver r1 = + new Rfc6724AddressSelectingDnsResolver(delegate, ProtocolFamilyPreference.DEFAULT, NO_SOURCE_ADDR); + final Rfc6724AddressSelectingDnsResolver r2 = + new Rfc6724AddressSelectingDnsResolver(delegate, ProtocolFamilyPreference.DEFAULT, NO_SOURCE_ADDR); + + final InetAddress[] out1 = r1.resolve("dual.example"); + final InetAddress[] out2 = r2.resolve("dual.example"); + + assertArrayEquals(out1, out2); + assertEquals(4, out1.length); + } + + @Test + void interleave_alternatesFamilies_preservingRelativeOrder_whenRfcSortIsNoop() throws Exception { + final InetAddress v6a = inet("2001:db8::1"); + final InetAddress v6b = inet("2001:db8::2"); + final InetAddress v4a = inet("192.0.2.1"); + final InetAddress v4b = inet("203.0.113.10"); + + // With NO_SOURCE_ADDR, RFC sort becomes a stable no-op; deterministic interleave. + delegate.add("dual.example", v6a, v6b, v4a, v4b); + + final Rfc6724AddressSelectingDnsResolver r = + new Rfc6724AddressSelectingDnsResolver(delegate, ProtocolFamilyPreference.INTERLEAVE, NO_SOURCE_ADDR); + + final InetAddress[] out = r.resolve("dual.example"); + assertEquals(Arrays.asList(v6a, v4a, v6b, v4b), Arrays.asList(out)); + } + + @Test + void preferIpv6_groupsAllV6First_preservingRelativeOrder_whenRfcSortIsNoop() throws Exception { + final InetAddress v4a = inet("192.0.2.1"); + final InetAddress v6a = inet("2001:db8::1"); + final InetAddress v4b = inet("203.0.113.10"); + final InetAddress v6b = inet("2001:db8::2"); + + delegate.add("dual.example", v4a, v6a, v4b, v6b); + + final Rfc6724AddressSelectingDnsResolver preferV6 = + new Rfc6724AddressSelectingDnsResolver(delegate, ProtocolFamilyPreference.PREFER_IPV6, NO_SOURCE_ADDR); + + final InetAddress[] out = preferV6.resolve("dual.example"); + assertEquals(Arrays.asList(v6a, v6b, v4a, v4b), Arrays.asList(out)); + assertInstanceOf(Inet6Address.class, out[0]); + } + + @Test + void filtersOutMulticastDestinations() throws Exception { + final InetAddress multicastV6 = inet("ff02::1"); + final InetAddress v6 = inet("2001:db8::1"); + + delegate.add("mcast.example", multicastV6, v6); + + final Rfc6724AddressSelectingDnsResolver r = + new Rfc6724AddressSelectingDnsResolver(delegate, ProtocolFamilyPreference.DEFAULT, NO_SOURCE_ADDR); + + final InetAddress[] out = r.resolve("mcast.example"); + assertEquals(1, out.length); + assertEquals(v6, out[0]); + } + + // ------------------------------------------------------------------------- + // New: direct tests for classifyScope(..) and Scope.fromValue(..) via reflection + // (Scope and classifyScope are private in the resolver). + // ------------------------------------------------------------------------- + + @Test + void classifyScope_loopback_linkLocal_siteLocal_global() throws Exception { + final Class resolverClass = Rfc6724AddressSelectingDnsResolver.class; + + assertEquals("INTERFACE_LOCAL", classifyScope(resolverClass, inet("127.0.0.1"))); + assertEquals("INTERFACE_LOCAL", classifyScope(resolverClass, inet("::1"))); + + assertEquals("LINK_LOCAL", classifyScope(resolverClass, inet("169.254.0.1"))); + assertEquals("LINK_LOCAL", classifyScope(resolverClass, inet("fe80::1"))); + + assertEquals("SITE_LOCAL", classifyScope(resolverClass, inet("10.0.0.1"))); + + assertEquals("GLOBAL", classifyScope(resolverClass, inet("8.8.8.8"))); + assertEquals("GLOBAL", classifyScope(resolverClass, inet("2003::1"))); + } + + @Test + void classifyScope_ipv6Multicast_usesLowNibbleScope() throws Exception { + final Class resolverClass = Rfc6724AddressSelectingDnsResolver.class; + + // ff01::1 -> scope 0x1 -> INTERFACE_LOCAL + assertEquals("INTERFACE_LOCAL", classifyScope(resolverClass, inet("ff01::1"))); + // ff02::1 -> scope 0x2 -> LINK_LOCAL + assertEquals("LINK_LOCAL", classifyScope(resolverClass, inet("ff02::1"))); + // ff04::1 -> scope 0x4 -> ADMIN_LOCAL + assertEquals("ADMIN_LOCAL", classifyScope(resolverClass, inet("ff04::1"))); + // ff05::1 -> scope 0x5 -> SITE_LOCAL + assertEquals("SITE_LOCAL", classifyScope(resolverClass, inet("ff05::1"))); + // ff08::1 -> scope 0x8 -> ORG_LOCAL + assertEquals("ORG_LOCAL", classifyScope(resolverClass, inet("ff08::1"))); + // ff0e::1 -> scope 0xe -> GLOBAL (default branch) + assertEquals("GLOBAL", classifyScope(resolverClass, inet("ff0e::1"))); + } + + @Test + void scopeFromValue_mapsKnownConstants_andDefaultsToGlobal() throws Exception { + final Class resolverClass = Rfc6724AddressSelectingDnsResolver.class; + final Class scopeClass = findDeclaredClass(resolverClass, "Scope"); + assertNotNull(scopeClass); + + assertEquals("INTERFACE_LOCAL", scopeFromValue(scopeClass, 0x1)); + assertEquals("LINK_LOCAL", scopeFromValue(scopeClass, 0x2)); + assertEquals("ADMIN_LOCAL", scopeFromValue(scopeClass, 0x4)); + assertEquals("SITE_LOCAL", scopeFromValue(scopeClass, 0x5)); + assertEquals("ORG_LOCAL", scopeFromValue(scopeClass, 0x8)); + + assertEquals("GLOBAL", scopeFromValue(scopeClass, 0x0)); + assertEquals("GLOBAL", scopeFromValue(scopeClass, 0xe)); + assertEquals("GLOBAL", scopeFromValue(scopeClass, 0xf)); + } + + @Test + void rfcRule2_prefersMatchingScope() throws Exception { + final InetAddress aDst = inet("2001:db8::1"); + final InetAddress bDst = inet("2001:db8::2"); + + // A matches scope (GLOBAL == GLOBAL); B mismatches (GLOBAL != LINK_LOCAL) + final InetAddress aSrc = inet("2001:db8::abcd"); + final InetAddress bSrc = inet("fe80::1"); + + delegate.add("t.example", bDst, aDst); + + final Rfc6724AddressSelectingDnsResolver r = + new Rfc6724AddressSelectingDnsResolver(delegate, ProtocolFamilyPreference.DEFAULT, sourceMap(aDst, aSrc, bDst, bSrc)); + + final InetAddress[] out = r.resolve("t.example"); + assertEquals(Arrays.asList(aDst, bDst), Arrays.asList(out)); + } + + @Test + void rfcRule5_prefersMatchingLabel() throws Exception { + final InetAddress aDst = inet("2001:db8::1"); // label 5 (2001::/32) + final InetAddress bDst = inet("2001:db8::2"); // label 5 + + final InetAddress aSrc = inet("2001:db8::abcd"); // label 5 -> matches A + final InetAddress bSrc = inet("::ffff:192.0.2.1"); // label 4 -> does not match B + + delegate.add("t.example", bDst, aDst); + + final Rfc6724AddressSelectingDnsResolver r = + new Rfc6724AddressSelectingDnsResolver(delegate, ProtocolFamilyPreference.DEFAULT, sourceMap(aDst, aSrc, bDst, bSrc)); + + final InetAddress[] out = r.resolve("t.example"); + assertEquals(Arrays.asList(aDst, bDst), Arrays.asList(out)); + } + + @Test + void rfcRule6_prefersHigherPrecedence() throws Exception { + final InetAddress aDst = inet("::1"); // precedence 50 (policy ::1) + final InetAddress bDst = inet("2001:db8::1"); // precedence 5 (policy 2001::/32) + + final InetAddress aSrc = inet("::1"); + final InetAddress bSrc = inet("2001:db8::abcd"); + + delegate.add("t.example", bDst, aDst); + + final Rfc6724AddressSelectingDnsResolver r = + new Rfc6724AddressSelectingDnsResolver(delegate, ProtocolFamilyPreference.DEFAULT, sourceMap(aDst, aSrc, bDst, bSrc)); + + final InetAddress[] out = r.resolve("t.example"); + assertEquals(Arrays.asList(aDst, bDst), Arrays.asList(out)); + } + + @Test + void rfcRule8_prefersSmallerScope_whenPrecedenceAndLabelTie() throws Exception { + // Both fall to ::/0 policy -> precedence 40, label 1, but different scopes. + final InetAddress aDst = inet("fe80::1"); // LINK_LOCAL scope (0x2) + final InetAddress bDst = inet("2003::1"); // GLOBAL scope (0xe) + + final InetAddress aSrc = inet("fe80::2"); // LINK_LOCAL, label 1 + final InetAddress bSrc = inet("2003::2"); // GLOBAL, label 1 + + delegate.add("t.example", bDst, aDst); + + final Rfc6724AddressSelectingDnsResolver r = + new Rfc6724AddressSelectingDnsResolver(delegate, ProtocolFamilyPreference.DEFAULT, sourceMap(aDst, aSrc, bDst, bSrc)); + + final InetAddress[] out = r.resolve("t.example"); + assertEquals(Arrays.asList(aDst, bDst), Arrays.asList(out)); + } + + @Test + void addr_fmt_simpleName() throws Exception { + final Class resolverClass = Rfc6724AddressSelectingDnsResolver.class; + + final Method addr = resolverClass.getDeclaredMethod("addr", InetAddress.class); + addr.setAccessible(true); + + final Method fmtArr = resolverClass.getDeclaredMethod("fmt", InetAddress[].class); + fmtArr.setAccessible(true); + + final Method fmtList = resolverClass.getDeclaredMethod("fmt", List.class); + fmtList.setAccessible(true); + + final Method simpleName = resolverClass.getDeclaredMethod("simpleName"); + simpleName.setAccessible(true); + + assertEquals("null", (String) addr.invoke(null, new Object[]{null})); + + final InetAddress v4 = inet("192.0.2.1"); + final InetAddress v6 = inet("2001:db8::1"); + + final String s4 = (String) addr.invoke(null, v4); + final String s6 = (String) addr.invoke(null, v6); + + assertEquals("IPv4(" + v4.getHostAddress() + ")", s4); + assertEquals("IPv6(" + v6.getHostAddress() + ")", s6); + + @SuppressWarnings("unchecked") final List arrOut = (List) fmtArr.invoke(null, new Object[]{new InetAddress[]{v6, v4}}); + assertEquals(Arrays.asList("IPv6(" + v6.getHostAddress() + ")", "IPv4(" + v4.getHostAddress() + ")"), arrOut); + + @SuppressWarnings("unchecked") final List listOut = (List) fmtList.invoke(null, Arrays.asList(v4, v6)); + assertEquals(Arrays.asList("IPv4(" + v4.getHostAddress() + ")", "IPv6(" + v6.getHostAddress() + ")"), listOut); + + assertNotNull((String) simpleName.invoke(null)); + assertEquals("Rfc6724Resolver", (String) simpleName.invoke(null)); + } + + private static InetAddress inet(final String s) { + try { + return InetAddress.getByName(s); + } catch (final UnknownHostException ex) { + throw new AssertionError(ex); + } + } + + private static Rfc6724AddressSelectingDnsResolver.SourceAddressResolver sourceMap( + final InetAddress aDst, final InetAddress aSrc, + final InetAddress bDst, final InetAddress bSrc) { + return (final InetSocketAddress dest) -> { + final InetAddress d = dest.getAddress(); + if (aDst.equals(d)) { + return aSrc; + } + if (bDst.equals(d)) { + return bSrc; + } + return null; + }; + } + + private static String classifyScope(final Class resolverClass, final InetAddress ip) throws Exception { + final Method m = resolverClass.getDeclaredMethod("classifyScope", InetAddress.class); + m.setAccessible(true); + final Object scope = m.invoke(null, ip); + return scope != null ? scope.toString() : null; + } + + private static String scopeFromValue(final Class scopeClass, final int v) throws Exception { + final Method m = scopeClass.getDeclaredMethod("fromValue", int.class); + m.setAccessible(true); + final Object scope = m.invoke(null, v); + return scope != null ? scope.toString() : null; + } + + private static Class findDeclaredClass(final Class outer, final String simpleName) { + for (final Class c : outer.getDeclaredClasses()) { + if (simpleName.equals(c.getSimpleName())) { + return c; + } + } + return null; + } +} diff --git a/httpclient5/src/test/java/org/apache/hc/client5/http/examples/Rfc6724ResolverExample.java b/httpclient5/src/test/java/org/apache/hc/client5/http/examples/Rfc6724ResolverExample.java new file mode 100644 index 0000000000..4113bcc4b8 --- /dev/null +++ b/httpclient5/src/test/java/org/apache/hc/client5/http/examples/Rfc6724ResolverExample.java @@ -0,0 +1,67 @@ +/* + * ==================================================================== + * 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 + * . + * + */ + +package org.apache.hc.client5.http.examples; + +import java.net.InetAddress; + +import org.apache.hc.client5.http.DnsResolver; +import org.apache.hc.client5.http.Rfc6724AddressSelectingDnsResolver; +import org.apache.hc.client5.http.SystemDefaultDnsResolver; +import org.apache.hc.client5.http.config.ProtocolFamilyPreference; + +public final class Rfc6724ResolverExample { + + public static void main(final String[] args) throws Exception { + final String host = args.length > 0 ? args[0] : "localhost"; + final ProtocolFamilyPreference pref = args.length > 1 + ? ProtocolFamilyPreference.valueOf(args[1]) + : ProtocolFamilyPreference.DEFAULT; + + final DnsResolver resolver = new Rfc6724AddressSelectingDnsResolver(SystemDefaultDnsResolver.INSTANCE, pref); + + final InetAddress[] out = resolver.resolve(host); + + System.out.println("Host: " + host); + System.out.println("Preference: " + pref); + if (out == null) { + System.out.println("Result: null"); + return; + } + if (out.length == 0) { + System.out.println("Result: []"); + return; + } + for (final InetAddress a : out) { + final String family = a instanceof java.net.Inet6Address ? "IPv6" : "IPv4"; + System.out.println(" " + family + " " + a.getHostAddress()); + } + } + + private Rfc6724ResolverExample() { + } +}