feat: Configure connections using DNS domain names

core/src/main/java/com/google/cloud/sql/core/Connector.java

@@ -49,6 +49,8 @@ class Connector {
   private final int serverProxyPort;
   private final ConnectorConfig config;
 
+  private final InstanceConnectionNameResolver instanceNameResolver;
+
   Connector(
       ConnectorConfig config,
       ConnectionInfoRepositoryFactory connectionInfoRepositoryFactory,
@@ -57,7 +59,8 @@ class Connector {
       ListenableFuture<KeyPair> localKeyPair,
       long minRefreshDelayMs,
       long refreshTimeoutMs,
-      int serverProxyPort) {
+      int serverProxyPort,
+      InstanceConnectionNameResolver instanceNameResolver) {
     this.config = config;
 
     this.adminApi =
@@ -67,6 +70,7 @@ class Connector {
     this.localKeyPair = localKeyPair;
     this.minRefreshDelayMs = minRefreshDelayMs;
     this.serverProxyPort = serverProxyPort;
+    this.instanceNameResolver = instanceNameResolver;
   }
 
   public ConnectorConfig getConfig() {
@@ -174,17 +178,16 @@ private ConnectionConfig resolveConnectionName(ConnectionConfig config) {
       final String unresolvedName = config.getDomainName();
       final Function<String, String> resolver =
           config.getConnectorConfig().getInstanceNameResolver();
+      CloudSqlInstanceName name;
       if (resolver != null) {
-        return config.withCloudSqlInstance(resolver.apply(unresolvedName));
+        name = instanceNameResolver.resolve(resolver.apply(unresolvedName));
       } else {
-        throw new IllegalStateException(
-            "Can't resolve domain " + unresolvedName + ". ConnectorConfig.resolver is not set.");
+        name = instanceNameResolver.resolve(unresolvedName);
       }
+      return config.withCloudSqlInstance(name.getConnectionName());
     } catch (IllegalArgumentException e) {
       throw new IllegalArgumentException(
-          String.format(
-              "Cloud SQL connection name is invalid: \"%s\"", config.getCloudSqlInstance()),
-          e);
+          String.format("Cloud SQL connection name is invalid: \"%s\"", config.getDomainName()), e);
     }
   }
 

core/src/main/java/com/google/cloud/sql/core/DnsInstanceConnectionNameResolver.java

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * 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 com.google.cloud.sql.core;
+
+import java.util.Collection;
+import java.util.Objects;
+import javax.naming.NameNotFoundException;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * An implementation of InstanceConnectionNameResolver that uses DNS TXT records to resolve an
+ * instance name from a domain name.
+ */
+class DnsInstanceConnectionNameResolver implements InstanceConnectionNameResolver {
+  private static final Logger logger =
+      LoggerFactory.getLogger(DnsInstanceConnectionNameResolver.class);
+
+  private final DnsResolver dnsResolver;
+
+  public DnsInstanceConnectionNameResolver(DnsResolver dnsResolver) {
+    this.dnsResolver = dnsResolver;
+  }
+
+  @Override
+  public CloudSqlInstanceName resolve(final String name) {
+    // Attempt to parse the instance name
+    try {
+      return new CloudSqlInstanceName(name);
+    } catch (IllegalArgumentException e) {
+      // Not a well-formed instance name.
+    }
+
+    // Next, attempt to resolve DNS name.
+    Collection<String> instanceNames;
+    try {
+      instanceNames = this.dnsResolver.resolveTxt(name);
+    } catch (NameNotFoundException ne) {
+      // No DNS record found. This is not a valid instance name.
+      throw new IllegalArgumentException(
+          String.format("Unable to resolve TXT record for \"%s\".", name));
+    }
+
+    // Use the first valid instance name from the list
+    // or throw an IllegalArgumentException if none of the values can be parsed.
+    return instanceNames.stream()
+        .map(
+            target -> {
+              try {
+                return new CloudSqlInstanceName(target);
+              } catch (IllegalArgumentException e) {
+                logger.info(
+                    "Unable to parse instance name in TXT record for "
+                        + "domain name \"{}\" with target \"{}\"",
+                    name,
+                    target,
+                    e);
+                return null;
+              }
+            })
+        .filter(Objects::nonNull)
+        .findFirst()
+        .orElseThrow(
+            () ->
+                new IllegalArgumentException(
+                    String.format("Unable to parse values of TXT record for \"%s\".", name)));
+  }
+}

core/src/main/java/com/google/cloud/sql/core/DnsResolver.java

@@ -19,6 +19,7 @@
 import java.util.Collection;
 import javax.naming.NameNotFoundException;
 
+/** Wraps the Java DNS API. */
 interface DnsResolver {
   Collection<String> resolveTxt(String domainName) throws NameNotFoundException;
 }

core/src/main/java/com/google/cloud/sql/core/InstanceConnectionNameResolver.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * 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 com.google.cloud.sql.core;
+
+/** Resolves the Cloud SQL Instance from the configuration name. */
+interface InstanceConnectionNameResolver {
+
+  /**
+   * Resolves the CloudSqlInstanceName from a configuration string value.
+   *
+   * @param name the configuration string
+   * @return the CloudSqlInstanceName
+   * @throws IllegalArgumentException if the name cannot be resolved.
+   */
+  CloudSqlInstanceName resolve(String name);
+}

core/src/main/java/com/google/cloud/sql/core/InternalConnectorRegistry.java

@@ -332,7 +332,8 @@ private Connector createConnector(ConnectorConfig config) {
         localKeyPair,
         MIN_REFRESH_DELAY_MS,
         connectTimeoutMs,
-        serverProxyPort);
+        serverProxyPort,
+        new DnsInstanceConnectionNameResolver(new JndiDnsResolver()));
   }
 
   /** Register the configuration for a named connector. */