iOS: Add includeUnroutableDNSResults to engine builder

docs/root/api/starting_envoy.rst

@@ -132,19 +132,17 @@ for further information.
   builder.addDNSFallbackNameservers(listOf<String>("8.8.8.8"))
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``enableDNSFilterUnroutableFamilies``
+``includeUnroutableDNSResults``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. attention::
-
-  This API is only available for Kotlin.
-
-Specify whether to filter unroutable IP families during DNS resolution or not.
-See `the Envoy docs <https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/network/dns_resolver/cares/v3/cares_dns_resolver.proto#extensions-network-dns-resolver-cares-v3-caresdnsresolverconfig>`__
+Specify whether to include unroutable IP families during DNS resolution or not.
+See the Envoy docs for
+`c-ares <https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/network/dns_resolver/cares/v3/cares_dns_resolver.proto#extensions-network-dns-resolver-cares-v3-caresdnsresolverconfig>`__ &
+`Apple <https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/network/dns_resolver/apple/v3/apple_dns_resolver.proto#extensions-network-dns-resolver-apple-v3-applednsresolverconfig>`__
 for further information.
 
-  // Kotlin
-  builder.enableDNSFilterUnroutableFamilies(true)
+  // Kotlin & Swift
+  builder.includeUnroutableDNSResults(true)
 
 ~~~~~~~~~~~~~~~
 ``addLogLevel``

library/java/io/envoyproxy/envoymobile/engine/EnvoyConfiguration.java

@@ -34,7 +34,7 @@ public enum TrustChainVerification {
   public final Integer dnsMinRefreshSeconds;
   public final String dnsPreresolveHostnames;
   public final List<String> dnsFallbackNameservers;
-  public final Boolean dnsFilterUnroutableFamilies;
+  public final Boolean includeUnroutableDNSResults;
   public final Boolean enableHappyEyeballs;
   public final Boolean enableInterfaceBinding;
   public final Integer h2ConnectionKeepaliveIdleIntervalMilliseconds;
@@ -68,7 +68,7 @@ public enum TrustChainVerification {
    * @param dnsMinRefreshSeconds         minimum rate in seconds at which to refresh DNS.
    * @param dnsPreresolveHostnames       hostnames to preresolve on Envoy Client construction.
    * @param dnsFallbackNameservers       addresses to use as DNS name server fallback.
-   * @param dnsFilterUnroutableFamilies  whether to filter unroutable IP families or not.
+   * @param includeUnroutableDNSResults  whether to include unroutable IP families or not.
    * @param enableHappyEyeballs          whether to enable RFC 6555 handling for IPv4/IPv6.
    * @param enableInterfaceBinding       whether to allow interface binding.
    * @param h2ConnectionKeepaliveIdleIntervalMilliseconds rate in milliseconds seconds to send h2
@@ -92,7 +92,7 @@ public EnvoyConfiguration(
       int connectTimeoutSeconds, int dnsRefreshSeconds, int dnsFailureRefreshSecondsBase,
       int dnsFailureRefreshSecondsMax, int dnsQueryTimeoutSeconds, int dnsMinRefreshSeconds,
       String dnsPreresolveHostnames, List<String> dnsFallbackNameservers,
-      Boolean dnsFilterUnroutableFamilies, boolean enableHappyEyeballs,
+      Boolean includeUnroutableDNSResults, boolean enableHappyEyeballs,
       boolean enableInterfaceBinding, int h2ConnectionKeepaliveIdleIntervalMilliseconds,
       int h2ConnectionKeepaliveTimeoutSeconds, List<String> h2RawDomains, int maxConnectionsPerHost,
       int statsFlushSeconds, int streamIdleTimeoutSeconds, int perTryIdleTimeoutSeconds,
@@ -111,7 +111,7 @@ public EnvoyConfiguration(
     this.dnsMinRefreshSeconds = dnsMinRefreshSeconds;
     this.dnsPreresolveHostnames = dnsPreresolveHostnames;
     this.dnsFallbackNameservers = dnsFallbackNameservers;
-    this.dnsFilterUnroutableFamilies = dnsFilterUnroutableFamilies;
+    this.includeUnroutableDNSResults = includeUnroutableDNSResults;
     this.enableHappyEyeballs = enableHappyEyeballs;
     this.enableInterfaceBinding = enableInterfaceBinding;
     this.h2ConnectionKeepaliveIdleIntervalMilliseconds =
@@ -191,7 +191,7 @@ String resolveTemplate(final String templateYAML, final String platformFilterTem
     String dnsResolverConfig = String.format(
         "{\"@type\":\"type.googleapis.com/envoy.extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig\",\"resolvers\":%s,\"use_resolvers_as_fallback\": %s, \"filter_unroutable_families\": %s}",
         dnsFallbackNameserversAsString, !dnsFallbackNameservers.isEmpty() ? "true" : "false",
-        dnsFilterUnroutableFamilies ? "true" : "false");
+        includeUnroutableDNSResults ? "false" : "true");
 
     StringBuilder configBuilder = new StringBuilder("!ignore platform_defs:\n");
     configBuilder.append(String.format("- &connect_timeout %ss\n", connectTimeoutSeconds))

library/kotlin/io/envoyproxy/envoymobile/EngineBuilder.kt

@@ -35,7 +35,7 @@ open class EngineBuilder(
   private var dnsFailureRefreshSecondsBase = 2
   private var dnsFailureRefreshSecondsMax = 10
   private var dnsFallbackNameservers = listOf<String>()
-  private var dnsFilterUnroutableFamilies = false
+  private var includeUnroutableDNSResults = false
   private var dnsQueryTimeoutSeconds = 25
   private var dnsMinRefreshSeconds = 60
   private var dnsPreresolveHostnames = "[]"
@@ -186,14 +186,14 @@ open class EngineBuilder(
   }
 
   /**
-   * Specify whether to filter unroutable IP families during DNS resolution or not.
+   * Specify whether to include unroutable IP families during DNS resolution or not.
    *
-   * @param dnsFilterUnroutableFamilies whether to filter or not.
+   * @param includeUnroutableDNSResults whether to include or not.
    *
    * @return this builder.
    */
-  fun enableDNSFilterUnroutableFamilies(dnsFilterUnroutableFamilies: Boolean): EngineBuilder {
-    this.dnsFilterUnroutableFamilies = dnsFilterUnroutableFamilies
+  fun includeUnroutableDNSResults(includeUnroutableDNSResults: Boolean): EngineBuilder {
+    this.includeUnroutableDNSResults = includeUnroutableDNSResults
     return this
   }
 
@@ -474,7 +474,7 @@ open class EngineBuilder(
       dnsMinRefreshSeconds,
       dnsPreresolveHostnames,
       dnsFallbackNameservers,
-      dnsFilterUnroutableFamilies,
+      includeUnroutableDNSResults,
       enableHappyEyeballs,
       enableInterfaceBinding,
       h2ConnectionKeepaliveIdleIntervalMilliseconds,

library/objective-c/EnvoyConfiguration.m

@@ -16,6 +16,7 @@ - (instancetype)initWithAdminInterfaceEnabled:(BOOL)adminInterfaceEnabled
                               enableHappyEyeballs:(BOOL)enableHappyEyeballs
                            enableInterfaceBinding:(BOOL)enableInterfaceBinding
                     enforceTrustChainVerification:(BOOL)enforceTrustChainVerification
+                      includeUnroutableDNSResults:(BOOL)includeUnroutableDNSResults
     h2ConnectionKeepaliveIdleIntervalMilliseconds:
         (UInt32)h2ConnectionKeepaliveIdleIntervalMilliseconds
               h2ConnectionKeepaliveTimeoutSeconds:(UInt32)h2ConnectionKeepaliveTimeoutSeconds
@@ -53,6 +54,7 @@ - (instancetype)initWithAdminInterfaceEnabled:(BOOL)adminInterfaceEnabled
   self.enableHappyEyeballs = enableHappyEyeballs;
   self.enableInterfaceBinding = enableInterfaceBinding;
   self.enforceTrustChainVerification = enforceTrustChainVerification;
+  self.includeUnroutableDNSResults = includeUnroutableDNSResults;
   self.h2ConnectionKeepaliveIdleIntervalMilliseconds =
       h2ConnectionKeepaliveIdleIntervalMilliseconds;
   self.h2ConnectionKeepaliveTimeoutSeconds = h2ConnectionKeepaliveTimeoutSeconds;
@@ -145,11 +147,12 @@ - (nullable NSString *)resolveTemplate:(NSString *)templateYAML {
                             self.enableHappyEyeballs ? @"true" : @"false"];
   [definitions appendFormat:@"- &dns_refresh_rate %lus\n", (unsigned long)self.dnsRefreshSeconds];
   [definitions appendFormat:@"- &dns_resolver_name envoy.network.dns_resolver.apple\n"];
-  // No additional values are currently needed for Apple-based DNS resolver.
   [definitions
       appendFormat:@"- &dns_resolver_config "
                    @"{\"@type\":\"type.googleapis.com/"
-                   @"envoy.extensions.network.dns_resolver.apple.v3.AppleDnsResolverConfig\"}\n"];
+                   @"envoy.extensions.network.dns_resolver.apple.v3.AppleDnsResolverConfig\", "
+                   @"\"include_unroutable_families\": %@}\n",
+                   self.includeUnroutableDNSResults ? @"true" : @"false"];
   [definitions appendFormat:@"- &enable_interface_binding %@\n",
                             self.enableInterfaceBinding ? @"true" : @"false"];
   [definitions appendFormat:@"- &trust_chain_verification %@\n", self.enforceTrustChainVerification

library/objective-c/EnvoyEngine.h

@@ -343,6 +343,7 @@ extern const int kEnvoyFilterResumeStatusResumeIteration;
 @property (nonatomic, assign) BOOL enableHappyEyeballs;
 @property (nonatomic, assign) BOOL enableInterfaceBinding;
 @property (nonatomic, assign) BOOL enforceTrustChainVerification;
+@property (nonatomic, assign) BOOL includeUnroutableDNSResults;
 @property (nonatomic, assign) UInt32 h2ConnectionKeepaliveIdleIntervalMilliseconds;
 @property (nonatomic, assign) UInt32 h2ConnectionKeepaliveTimeoutSeconds;
 @property (nonatomic, strong) NSArray<NSString *> *h2RawDomains;
@@ -374,6 +375,7 @@ extern const int kEnvoyFilterResumeStatusResumeIteration;
                               enableHappyEyeballs:(BOOL)enableHappyEyeballs
                            enableInterfaceBinding:(BOOL)enableInterfaceBinding
                     enforceTrustChainVerification:(BOOL)enforceTrustChainVerification
+                      includeUnroutableDNSResults:(BOOL)includeUnroutableDNSResults
     h2ConnectionKeepaliveIdleIntervalMilliseconds:
         (UInt32)h2ConnectionKeepaliveIdleIntervalMilliseconds
               h2ConnectionKeepaliveTimeoutSeconds:(UInt32)h2ConnectionKeepaliveTimeoutSeconds

library/swift/EngineBuilder.swift

@@ -25,6 +25,7 @@ open class EngineBuilder: NSObject {
   private var enableHappyEyeballs: Bool = false
   private var enableInterfaceBinding: Bool = false
   private var enforceTrustChainVerification: Bool = true
+  private var includeUnroutableDNSResults: Bool = false
   private var h2ConnectionKeepaliveIdleIntervalMilliseconds: UInt32 = 100000000
   private var h2ConnectionKeepaliveTimeoutSeconds: UInt32 = 10
   private var h2RawDomains: [String] = []
@@ -186,6 +187,19 @@ open class EngineBuilder: NSObject {
     return self
   }
 
+  /// Specify whether DNS addresses that the system considers to be unroutable should still
+  /// be attempted.
+  ///
+  /// - parameter includeUnroutableDNSResults: whether to include unroutable families of DNS
+  ///                                          addresses.
+  ///
+  /// - returns: This builder.
+  @discardableResult
+  public func includeUnroutableDNSResults(_ includeUnroutableDNSResults: Bool) -> Self {
+    self.includeUnroutableDNSResults = includeUnroutableDNSResults
+    return self
+  }
+
   /// Add a rate at which to ping h2 connections on new stream creation if the connection has
   /// sat idle.
   ///
@@ -430,6 +444,7 @@ open class EngineBuilder: NSObject {
       enableHappyEyeballs: self.enableHappyEyeballs,
       enableInterfaceBinding: self.enableInterfaceBinding,
       enforceTrustChainVerification: self.enforceTrustChainVerification,
+      includeUnroutableDNSResults: self.includeUnroutableDNSResults,
       h2ConnectionKeepaliveIdleIntervalMilliseconds:
         self.h2ConnectionKeepaliveIdleIntervalMilliseconds,
       h2ConnectionKeepaliveTimeoutSeconds: self.h2ConnectionKeepaliveTimeoutSeconds,

test/kotlin/io/envoyproxy/envoymobile/EngineBuilderTest.kt

@@ -121,13 +121,13 @@ class EngineBuilderTest {
   }
 
   @Test
-  fun `specifying dns filter unroutable families overrides default`() {
+  fun `specifying dns include unroutable families overrides default`() {
     engineBuilder = EngineBuilder(Standard())
     engineBuilder.addEngineType { envoyEngine }
-    engineBuilder.enableDNSFilterUnroutableFamilies(true)
+    engineBuilder.includeUnroutableDNSResults(true)
 
     val engine = engineBuilder.build() as EngineImpl
-    assertThat(engine.envoyConfiguration!!.dnsFilterUnroutableFamilies).isTrue()
+    assertThat(engine.envoyConfiguration!!.includeUnroutableDNSResults).isTrue()
   }
 
   @Test

test/swift/EngineBuilderTests.swift

@@ -418,6 +418,7 @@ final class EngineBuilderTests: XCTestCase {
       enableHappyEyeballs: true,
       enableInterfaceBinding: true,
       enforceTrustChainVerification: false,
+      includeUnroutableDNSResults: true,
       h2ConnectionKeepaliveIdleIntervalMilliseconds: 1,
       h2ConnectionKeepaliveTimeoutSeconds: 333,
       h2RawDomains: ["h2-raw.domain"],
@@ -494,6 +495,7 @@ final class EngineBuilderTests: XCTestCase {
       enableHappyEyeballs: false,
       enableInterfaceBinding: false,
       enforceTrustChainVerification: true,
+      includeUnroutableDNSResults: false,
       h2ConnectionKeepaliveIdleIntervalMilliseconds: 1,
       h2ConnectionKeepaliveTimeoutSeconds: 333,
       h2RawDomains: [],
@@ -535,6 +537,7 @@ final class EngineBuilderTests: XCTestCase {
       enableHappyEyeballs: false,
       enableInterfaceBinding: false,
       enforceTrustChainVerification: true,
+      includeUnroutableDNSResults: false,
       h2ConnectionKeepaliveIdleIntervalMilliseconds: 222,
       h2ConnectionKeepaliveTimeoutSeconds: 333,
       h2RawDomains: [],