feat: Automatially configure connections using DNS

Author: hessjcg

README.md

@@ -234,6 +234,63 @@ func connect() {
     // ... etc
 }
 ```
+### Using DNS to identify an instance
+
+The connector can be configured to use DNS to look up an instance. This would
+allow you to configure your application to connect to a database instance, and
+centrally configure which instance in your DNS zone.
+
+#### Configure your DNS Records
+
+Add a DNS SRV record for the Cloud SQL instance to a **private** DNS server 
+or a private Google Cloud DNS Zone used by your application. 
+
+**Note:** You are strongly discouraged from adding DNS records for your 
+Cloud SQL instances to a public DNS server. This would allow anyone on the
+internet to discover the Cloud SQL instance name. 
+
+For example: suppose you wanted to use the domain name 
+`prod-db.mycompany.example.com` to connect to your database instance 
+`my-project:region:my-instance`. 
+
+- Record type: `SRV` 
+- Name: `prod-db.mycompany.example.com` – This is the domain name used by the application
+- Target: `my-project:region:my-instance` – This is the instance name
+- Port: `3307` – always use port 3307
+- Priority: `0` – always use priority 0 
+- Weight: `1` - always use weight 1
+
+#### Configure the connector
+
+Configure the connector as described above, replacing the conenctor ID with
+the DNS name. 
+
+Adapting the MySQL + database/sql example above:
+
+```go
+import (
+    "database/sql"
+
+    "cloud.google.com/go/cloudsqlconn"
+    "cloud.google.com/go/cloudsqlconn/mysql/mysql"
+)
+
+func connect() {
+    cleanup, err := mysql.RegisterDriver("cloudsql-mysql", cloudsqlconn.WithCredentialsFile("key.json"))
+    if err != nil {
+        // ... handle error
+    }
+    // call cleanup when you're done with the database connection
+    defer cleanup()
+
+    db, err := sql.Open(
+        "cloudsql-mysql",
+        "myuser:mypass@cloudsql-mysql(prod-db.mycompany.example.com)/mydb",
+    )
+    // ... etc
+}
+```
+
 
 ### Using Options
 

dialer.go

@@ -24,6 +24,7 @@ import (
 	"fmt"
 	"io"
 	"net"
+	"sort"
 	"strings"
 	"sync"
 	"sync/atomic"
@@ -153,6 +154,10 @@ type Dialer struct {
 
 	// iamTokenSource supplies the OAuth2 token used for IAM DB Authn.
 	iamTokenSource oauth2.TokenSource
+
+	// resolver does SRV record DNS lookups when resolving DNS name dialer
+	// configuration.
+	resolver NetResolver
 }
 
 var (
@@ -253,6 +258,11 @@ func NewDialer(ctx context.Context, opts ...Option) (*Dialer, error) {
 	if err != nil {
 		return nil, err
 	}
+	var r NetResolver = net.DefaultResolver
+	if cfg.resolver != nil {
+		r = cfg.resolver
+	}
+
 	d := &Dialer{
 		closed:            make(chan struct{}),
 		cache:             make(map[instance.ConnName]monitoredCache),
@@ -265,10 +275,25 @@ func NewDialer(ctx context.Context, opts ...Option) (*Dialer, error) {
 		dialerID:          uuid.New().String(),
 		iamTokenSource:    cfg.iamLoginTokenSource,
 		dialFunc:          cfg.dialFunc,
+		resolver:          r,
 	}
 	return d, nil
 }
 
+func (d *Dialer) resolveInstanceName(ctx context.Context, icn string) (instance.ConnName, error) {
+	cn, err := instance.ParseConnName(icn)
+	if err != nil {
+		// The connection name was not project:region:instance
+		// Attempt to query a SRV record and see if it works instead.
+		cn, err = d.queryDNS(ctx, icn)
+		if err != nil {
+			return instance.ConnName{}, err
+		}
+	}
+
+	return cn, nil
+}
+
 // Dial returns a net.Conn connected to the specified Cloud SQL instance. The
 // icn argument must be the instance's connection name, which is in the format
 // "project-name:region:instance-name".
@@ -288,7 +313,7 @@ func (d *Dialer) Dial(ctx context.Context, icn string, opts ...DialOption) (conn
 		go trace.RecordDialError(context.Background(), icn, d.dialerID, err)
 		endDial(err)
 	}()
-	cn, err := instance.ParseConnName(icn)
+	cn, err := d.resolveInstanceName(ctx, icn)
 	if err != nil {
 		return nil, err
 	}
@@ -429,7 +454,7 @@ func validClientCert(
 // the instance:
 // https://cloud.google.com/sql/docs/mysql/admin-api/rest/v1beta4/SqlDatabaseVersion
 func (d *Dialer) EngineVersion(ctx context.Context, icn string) (string, error) {
-	cn, err := instance.ParseConnName(icn)
+	cn, err := d.resolveInstanceName(ctx, icn)
 	if err != nil {
 		return "", err
 	}
@@ -449,7 +474,7 @@ func (d *Dialer) EngineVersion(ctx context.Context, icn string) (string, error)
 // Use Warmup to start the refresh process early if you don't know when you'll
 // need to call "Dial".
 func (d *Dialer) Warmup(ctx context.Context, icn string, opts ...DialOption) error {
-	cn, err := instance.ParseConnName(icn)
+	cn, err := d.resolveInstanceName(ctx, icn)
 	if err != nil {
 		return err
 	}
@@ -565,3 +590,59 @@ func (d *Dialer) connectionInfoCache(
 
 	return c, nil
 }
+
+// queryDNS attempts to resolve a SRV record for the domain name.
+// The DNS SRV record's target field is used as instance name.
+//
+// This handles several conditions where the DNS records may be missing or
+// invalid:
+//   - The domain name resolves to 0 DNS records - return an error
+//   - Some DNS records to not contain a well-formed instance name - return the
+//     first well-formed instance name. If none found return an error.
+//   - The domain name resolves to 2 or more DNS record - return first valid
+//     record when sorted by priority: lowest value first, then by target:
+//     alphabetically.
+func (d *Dialer) queryDNS(ctx context.Context, domainName string) (instance.ConnName, error) {
+	// Attempt to query the SRV records.
+	// This could return a partial error where both err != nil && len(records) > 0.
+	_, records, err := d.resolver.LookupSRV(ctx, "", "", domainName)
+
+	// Process the records returning the first valid SRV record.
+
+	// Sort the record slice so that lowest priority comes first, then
+	// alphabetically by instance name
+	sort.Slice(records, func(i, j int) bool {
+		if records[i].Priority == records[j].Priority {
+			return records[i].Target < records[j].Target
+		}
+		return records[i].Priority < records[j].Priority
+	})
+
+	var perr error
+	// Attempt to parse records, returning the first valid record.
+	for _, record := range records {
+		// Remove trailing '.' from target value.
+		target := strings.TrimRight(record.Target, ".")
+
+		// Parse the target as a CN
+		cn, parseErr := instance.ParseConnName(target)
+		if parseErr != nil {
+			perr = fmt.Errorf("unable to parse SRV for %q: %v", domainName, parseErr)
+			continue
+		}
+		return cn, nil
+	}
+
+	// If resolve failed and no records were found, return the error.
+	if err != nil {
+		return instance.ConnName{}, fmt.Errorf("unable to resolve SRV record for %q: %v", domainName, err)
+	}
+
+	// If all the records failed to parse, return one of the parse errors
+	if perr != nil {
+		return instance.ConnName{}, perr
+	}
+
+	// No records were found, return an error.
+	return instance.ConnName{}, fmt.Errorf("no valid SRV records found for %q", domainName)
+}

dialer_test.go

@@ -1016,3 +1016,92 @@ func TestDialerInitializesLazyCache(t *testing.T) {
 		t.Fatalf("dialer was initialized with non-lazy type: %T", tt)
 	}
 }
+
+type fakeResolver struct{}
+
+func (r *fakeResolver) LookupSRV(_ context.Context, _, _, name string) (cname string, addrs []*net.SRV, err error) {
+	// For TestDialerSuccessfullyDialsDnsSrvRecord
+	if name == "db.example.com" {
+		return "", []*net.SRV{
+			&net.SRV{Target: "my-project:my-region:my-instance."},
+		}, nil
+	}
+	if name == "db2.example.com" {
+		return "", []*net.SRV{
+			&net.SRV{Target: "my-project:my-region:my-instance"},
+		}, nil
+	}
+	// For TestDialerFailsDnsSrvRecordMalformed
+	if name == "malformed.example.com" {
+		return "", []*net.SRV{
+			&net.SRV{Target: "an-invalid-instance-name"},
+		}, nil
+	}
+	return "", nil, fmt.Errorf("no resolution for %v", name)
+}
+
+func TestDialerSuccessfullyDialsDnsSrvRecord(t *testing.T) {
+	inst := mock.NewFakeCSQLInstance(
+		"my-project", "my-region", "my-instance",
+	)
+	d := setupDialer(t, setupConfig{
+		testInstance: inst,
+		reqs: []*mock.Request{
+			mock.InstanceGetSuccess(inst, 1),
+			mock.CreateEphemeralSuccess(inst, 1),
+		},
+		dialerOptions: []Option{
+			WithTokenSource(mock.EmptyTokenSource{}),
+			WithResolver(&fakeResolver{}),
+		},
+	})
+
+	// Target has a trailing '.'
+	testSuccessfulDial(
+		context.Background(), t, d,
+		"db.example.com",
+	)
+	// Target does not have a trailing '.'
+	testSuccessfulDial(
+		context.Background(), t, d,
+		"db2.example.com",
+	)
+}
+
+func TestDialerFailsDnsSrvRecordMissing(t *testing.T) {
+	inst := mock.NewFakeCSQLInstance(
+		"my-project", "my-region", "my-instance",
+	)
+	d := setupDialer(t, setupConfig{
+		testInstance: inst,
+		reqs:         []*mock.Request{},
+		dialerOptions: []Option{
+			WithTokenSource(mock.EmptyTokenSource{}),
+			WithResolver(&fakeResolver{}),
+		},
+	})
+	_, err := d.Dial(context.Background(), "doesnt-exist.example.com")
+	wantMsg := "unable to resolve SRV record for doesnt-exist.example.com"
+	if !strings.Contains(err.Error(), wantMsg) {
+		t.Fatalf("want = %v, got = %v", wantMsg, err)
+	}
+}
+
+func TestDialerFailsDnsSrvRecordMalformed(t *testing.T) {
+	inst := mock.NewFakeCSQLInstance(
+		"my-project", "my-region", "my-instance",
+	)
+	d := setupDialer(t, setupConfig{
+		testInstance: inst,
+		reqs:         []*mock.Request{},
+		dialerOptions: []Option{
+			WithTokenSource(mock.EmptyTokenSource{}),
+			WithResolver(&fakeResolver{}),
+		},
+	})
+	_, err := d.Dial(context.Background(), "malformed.example.com")
+	wantMsg := "unable to parse SRV for malformed.example.com"
+	if !strings.Contains(err.Error(), wantMsg) {
+		t.Fatalf("want = %v, got = %v", wantMsg, err)
+	}
+}

options.go

@@ -52,6 +52,7 @@ type dialerConfig struct {
 	setCredentials         bool
 	setTokenSource         bool
 	setIAMAuthNTokenSource bool
+	resolver               NetResolver
 	// err tracks any dialer options that may have failed.
 	err error
 }
@@ -234,6 +235,24 @@ func WithIAMAuthN() Option {
 	}
 }
 
+// NetResolver groups the methods on net.Resolver that are used by the DNS
+// resolver implementation. This allows an application to replace the default
+// net.DefaultResolver with a custom implementation. For example: the
+// application may need to connect to a specific DNS server using a specially
+// configured instance of net.Resolver.
+type NetResolver interface {
+	LookupSRV(ctx context.Context, service, proto, name string) (cname string, addrs []*net.SRV, err error)
+}
+
+// WithResolver replaces the default DNS resolver with an alternate
+// implementation to use when resolving SRV records containing the
+// instance name. By default, the dialer will use net.DefaultResolver.
+func WithResolver(r NetResolver) Option {
+	return func(d *dialerConfig) {
+		d.resolver = r
+	}
+}
+
 type debugLoggerWithoutContext struct {
 	logger debug.Logger
 }