chore: Add domain name to the connector config. (#2098)

Add DomainName to connection config, and an InstanceNameResolver function. This will allow the connector
to be configured using a domain name referencing the instead of the instance name.

This is part of the implementation of #2043.

Author: hessjcg

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

@@ -19,6 +19,7 @@
 import com.google.auth.oauth2.GoogleCredentials;
 import com.google.common.base.Objects;
 import java.util.List;
+import java.util.function.Function;
 import java.util.function.Supplier;
 
 /**
@@ -33,6 +34,7 @@ public class ConnectorConfig {
   private final String adminRootUrl;
   private final String adminServicePath;
   private final Supplier<GoogleCredentials> googleCredentialsSupplier;
+  private final Function<String, String> instanceNameResolver;
   private final GoogleCredentials googleCredentials;
   private final String googleCredentialsPath;
   private final String adminQuotaProject;
@@ -50,7 +52,8 @@ private ConnectorConfig(
       String googleCredentialsPath,
       String adminQuotaProject,
       String universeDomain,
-      RefreshStrategy refreshStrategy) {
+      RefreshStrategy refreshStrategy,
+      Function<String, String> instanceNameResolver) {
     this.targetPrincipal = targetPrincipal;
     this.delegates = delegates;
     this.adminRootUrl = adminRootUrl;
@@ -61,6 +64,7 @@ private ConnectorConfig(
     this.adminQuotaProject = adminQuotaProject;
     this.universeDomain = universeDomain;
     this.refreshStrategy = refreshStrategy;
+    this.instanceNameResolver = instanceNameResolver;
   }
 
   @Override
@@ -81,7 +85,8 @@ public boolean equals(Object o) {
         && Objects.equal(googleCredentialsPath, that.googleCredentialsPath)
         && Objects.equal(adminQuotaProject, that.adminQuotaProject)
         && Objects.equal(universeDomain, that.universeDomain)
-        && Objects.equal(refreshStrategy, that.refreshStrategy);
+        && Objects.equal(refreshStrategy, that.refreshStrategy)
+        && Objects.equal(instanceNameResolver, that.instanceNameResolver);
   }
 
   @Override
@@ -96,7 +101,8 @@ public int hashCode() {
         googleCredentialsPath,
         adminQuotaProject,
         universeDomain,
-        refreshStrategy);
+        refreshStrategy,
+        instanceNameResolver);
   }
 
   public String getTargetPrincipal() {
@@ -139,6 +145,10 @@ public RefreshStrategy getRefreshStrategy() {
     return refreshStrategy;
   }
 
+  public Function<String, String> getInstanceNameResolver() {
+    return instanceNameResolver;
+  }
+
   /** The builder for the ConnectionConfig. */
   public static class Builder {
 
@@ -152,6 +162,7 @@ public static class Builder {
     private String adminQuotaProject;
     private String universeDomain;
     private RefreshStrategy refreshStrategy = RefreshStrategy.BACKGROUND;
+    private Function<String, String> instanceNameResolver;
 
     /** Chained setter for TargetPrinciple field. */
     public Builder withTargetPrincipal(String targetPrincipal) {
@@ -214,6 +225,12 @@ public Builder withRefreshStrategy(RefreshStrategy refreshStrategy) {
       return this;
     }
 
+    /** Chained setter for the InstanceNameResolver field. */
+    public Builder withInstanceNameResolver(Function<String, String> instanceNameResolver) {
+      this.instanceNameResolver = instanceNameResolver;
+      return this;
+    }
+
     /** Builds a new instance of {@code ConnectionConfig}. */
     public ConnectorConfig build() {
       // validate only one GoogleCredentials configuration field set
@@ -248,7 +265,8 @@ public ConnectorConfig build() {
           googleCredentialsPath,
           adminQuotaProject,
           universeDomain,
-          refreshStrategy);
+          refreshStrategy,
+          instanceNameResolver);
     }
   }
 }

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

@@ -31,28 +31,81 @@ class CloudSqlInstanceName {
   // Some legacy project ids are domain-scoped (e.g. "example.com:PROJECT:REGION:INSTANCE")
   private static final Pattern CONNECTION_NAME =
       Pattern.compile("([^:]+(:[^:]+)?):([^:]+):([^:]+)");
+
+  /**
+   * The domain name pattern in accordance with RFC 1035, RFC 1123 and RFC 2181.
+   *
+   * <p>Explanation of the Regex:
+   *
+   * <p>^: Matches the beginning of the string.<br>
+   * (?=.{1,255}$): Positive lookahead assertion to ensure the domain name is between 1 and 255
+   * characters long.<br>
+   * (?!-): Negative lookahead assertion to prevent hyphens at the beginning.<br>
+   * [A-Za-z0-9-]+: Matches one or more alphanumeric characters or hyphens.<br>
+   * (\\.[A-Za-z0-9-]+)*: Matches zero or more occurrences of a period followed by one or more
+   * alphanumeric characters or hyphens (for subdomains).<br>
+   * \\.: Matches a period before the TLD.<br>
+   * [A-Za-z]{2,}: Matches two or more letters for the TLD.<br>
+   * $: Matches the end of the string.<br>
+   */
+  private static final Pattern DOMAIN_NAME =
+      Pattern.compile("^(?=.{1,255}$)(?!-)[A-Za-z0-9-]+(\\.[A-Za-z0-9-]+)*\\.[A-Za-z]{2,}$");
+
   private final String projectId;
   private final String regionId;
   private final String instanceId;
   private final String connectionName;
+  private final String domainName;
+
+  /**
+   * Validates that a string is a well-formed domain name.
+   *
+   * @param domain the domain name to check
+   * @return true if domain is a well-formed domain name.
+   */
+  public static boolean isValidDomain(String domain) {
+    Matcher matcher = DOMAIN_NAME.matcher(domain);
+    return matcher.matches();
+  }
 
   /**
    * Initializes a new CloudSqlInstanceName class.
    *
    * @param connectionName instance connection name in the format "PROJECT_ID:REGION_ID:INSTANCE_ID"
    */
   CloudSqlInstanceName(String connectionName) {
-    this.connectionName = connectionName;
+    this(connectionName, null);
+  }
+
+  /**
+   * Initializes a new CloudSqlInstanceName class containing the domain name.
+   *
+   * @param connectionName instance connection name in the format "PROJECT_ID:REGION_ID:INSTANCE_ID"
+   * @param domainName the domain name used to look up the instance, or null.
+   */
+  CloudSqlInstanceName(String connectionName, String domainName) {
     Matcher matcher = CONNECTION_NAME.matcher(connectionName);
     checkArgument(
         matcher.matches(),
         String.format(
             "[%s] Cloud SQL connection name is invalid, expected string in the form of"
                 + " \"<PROJECT_ID>:<REGION_ID>:<INSTANCE_ID>\".",
             connectionName));
+    this.connectionName = connectionName;
     this.projectId = matcher.group(1);
     this.regionId = matcher.group(3);
     this.instanceId = matcher.group(4);
+
+    // Only set this.domainName when it is not empty
+    if (domainName != null && !domainName.isEmpty()) {
+      Matcher domainMatcher = DOMAIN_NAME.matcher(domainName);
+      checkArgument(
+          domainMatcher.matches(),
+          String.format("[%s] Domain name is invalid, expected a valid domain name", domainName));
+      this.domainName = domainName;
+    } else {
+      this.domainName = null;
+    }
   }
 
   String getConnectionName() {
@@ -71,6 +124,10 @@ String getInstanceId() {
     return instanceId;
   }
 
+  String getDomainName() {
+    return domainName;
+  }
+
   @Override
   public String toString() {
     return connectionName;

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

@@ -63,9 +63,19 @@ public class ConnectionConfig {
 
   private final AuthType authType;
   private final String unixSocketPathSuffix;
+  private final String domainName;
 
   /** Create a new ConnectionConfig from the well known JDBC Connection properties. */
   public static ConnectionConfig fromConnectionProperties(Properties props) {
+    // TODO convert internal uses to fromConnectionProperties(props, domainName)
+    return fromConnectionProperties(props, null);
+  }
+
+  /**
+   * Create a new ConnectionConfig from the well known JDBC Connection properties, also setting
+   * database domain name.
+   */
+  public static ConnectionConfig fromConnectionProperties(Properties props, String domainName) {
     final String csqlInstanceName = props.getProperty(ConnectionConfig.CLOUD_SQL_INSTANCE_PROPERTY);
     final String namedConnection =
         props.getProperty(ConnectionConfig.CLOUD_SQL_NAMED_CONNECTOR_PROPERTY);
@@ -113,6 +123,7 @@ public static ConnectionConfig fromConnectionProperties(Properties props) {
         ipTypes,
         authType,
         unixSocketPathSuffix,
+        domainName,
         new ConnectorConfig.Builder()
             .withTargetPrincipal(targetPrincipal)
             .withDelegates(delegates)
@@ -162,13 +173,20 @@ public boolean equals(Object o) {
         && Objects.equals(unixSocketPath, config.unixSocketPath)
         && Objects.equals(ipTypes, config.ipTypes)
         && Objects.equals(authType, config.authType)
+        && Objects.equals(domainName, config.domainName)
         && Objects.equals(connectorConfig, config.connectorConfig);
   }
 
   @Override
   public int hashCode() {
     return Objects.hash(
-        cloudSqlInstance, namedConnector, unixSocketPath, ipTypes, authType, connectorConfig);
+        cloudSqlInstance,
+        namedConnector,
+        unixSocketPath,
+        ipTypes,
+        authType,
+        domainName,
+        connectorConfig);
   }
 
   private ConnectionConfig(
@@ -178,6 +196,7 @@ private ConnectionConfig(
       List<IpType> ipTypes,
       AuthType authType,
       String unixSocketPathSuffix,
+      String domainName,
       ConnectorConfig connectorConfig) {
     this.cloudSqlInstance = cloudSqlInstance;
     this.namedConnector = namedConnector;
@@ -186,6 +205,7 @@ private ConnectionConfig(
     this.unixSocketPathSuffix = unixSocketPathSuffix;
     this.connectorConfig = connectorConfig;
     this.authType = authType;
+    this.domainName = domainName;
   }
 
   /** Creates a new instance of the ConnectionConfig with an updated connectorConfig. */
@@ -197,9 +217,36 @@ public ConnectionConfig withConnectorConfig(ConnectorConfig config) {
         ipTypes,
         authType,
         unixSocketPathSuffix,
+        domainName,
         config);
   }
 
+  /** Creates a new instance of the ConnectionConfig with an updated cloudSqlInstance. */
+  public ConnectionConfig withCloudSqlInstance(String newCloudSqlInstance) {
+    return new ConnectionConfig(
+        newCloudSqlInstance,
+        namedConnector,
+        unixSocketPath,
+        ipTypes,
+        authType,
+        unixSocketPathSuffix,
+        domainName,
+        connectorConfig);
+  }
+
+  /** Creates a new instance of the ConnectionConfig with an updated cloudSqlInstance. */
+  public ConnectionConfig withDomainName(String domainName) {
+    return new ConnectionConfig(
+        cloudSqlInstance,
+        namedConnector,
+        unixSocketPath,
+        ipTypes,
+        authType,
+        unixSocketPathSuffix,
+        domainName,
+        connectorConfig);
+  }
+
   public String getNamedConnector() {
     return namedConnector;
   }
@@ -228,6 +275,10 @@ public AuthType getAuthType() {
     return authType;
   }
 
+  public String getDomainName() {
+    return domainName;
+  }
+
   /** The builder for the ConnectionConfig. */
   public static class Builder {
 
@@ -238,6 +289,7 @@ public static class Builder {
     private String unixSocketPathSuffix;
     private ConnectorConfig connectorConfig = new ConnectorConfig.Builder().build();
     private AuthType authType = DEFAULT_AUTH_TYPE;
+    private String domainName;
 
     /** Chained setter for CloudSqlInstance field. */
     public Builder withCloudSqlInstance(String cloudSqlInstance) {
@@ -281,6 +333,12 @@ public Builder withIpTypes(List<IpType> ipTypes) {
       return this;
     }
 
+    /** Set domainName. */
+    public Builder withDomainName(String domainName) {
+      this.domainName = domainName;
+      return this;
+    }
+
     /** Chained setter for UnixSocketPathSuffix field. */
     public Builder withUnixSocketPathSuffix(String unixSocketPathSuffix) {
       this.unixSocketPathSuffix = unixSocketPathSuffix;
@@ -296,6 +354,7 @@ public ConnectionConfig build() {
           ipTypes,
           authType,
           unixSocketPathSuffix,
+          domainName,
           connectorConfig);
     }
   }

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

@@ -28,6 +28,7 @@
 import java.security.KeyPair;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ExecutionException;
+import java.util.function.Function;
 import javax.net.ssl.SSLSocket;
 import jnr.unixsocket.UnixSocketAddress;
 import jnr.unixsocket.UnixSocketChannel;
@@ -140,9 +141,11 @@ Socket connect(ConnectionConfig config, long timeoutMs) throws IOException {
     }
   }
 
-  ConnectionInfoCache getConnection(ConnectionConfig config) {
+  ConnectionInfoCache getConnection(final ConnectionConfig config) {
+    final ConnectionConfig updatedConfig = resolveConnectionName(config);
+
     ConnectionInfoCache instance =
-        instances.computeIfAbsent(config, k -> createConnectionInfo(config));
+        instances.computeIfAbsent(updatedConfig, k -> createConnectionInfo(updatedConfig));
 
     // If the client certificate has expired (as when the computer goes to
     // sleep, and the refresh cycle cannot run), force a refresh immediately.
@@ -154,6 +157,44 @@ ConnectionInfoCache getConnection(ConnectionConfig config) {
     return instance;
   }
 
+  /**
+   * Updates the ConnectionConfig to ensure that the cloudSqlInstance field is set, resolving the
+   * domainName using the InstanceNameResolver.
+   *
+   * @param config the configuration to resolve.
+   * @return a ConnectionConfig guaranteed to have the CloudSqlInstance field set.
+   */
+  private ConnectionConfig resolveConnectionName(ConnectionConfig config) {
+    // If domainName is not set, return the original configuration unmodified.
+    if (config.getDomainName() == null || config.getDomainName().isEmpty()) {
+      return config;
+    }
+
+    // If both domainName and cloudSqlInstance are set, ignore the domain name. Return a new
+    // configuration with domainName set to null.
+    if (config.getCloudSqlInstance() != null && !config.getCloudSqlInstance().isEmpty()) {
+      return config.withDomainName(null);
+    }
+
+    // If only domainName is set, resolve the domain name.
+    try {
+      final String unresolvedName = config.getDomainName();
+      final Function<String, String> resolver =
+          config.getConnectorConfig().getInstanceNameResolver();
+      if (resolver != null) {
+        return config.withCloudSqlInstance(resolver.apply(unresolvedName));
+      } else {
+        throw new IllegalStateException(
+            "Can't resolve domain " + unresolvedName + ". ConnectorConfig.resolver is not set.");
+      }
+    } catch (IllegalArgumentException e) {
+      throw new IllegalArgumentException(
+          String.format(
+              "Cloud SQL connection name is invalid: \"%s\"", config.getCloudSqlInstance()),
+          e);
+    }
+  }
+
   private ConnectionInfoCache createConnectionInfo(ConnectionConfig config) {
     logger.debug(
         String.format("[%s] Connection info added to cache.", config.getCloudSqlInstance()));