Update docs and examples and tests to use NewClient instead of Dial

Documentation/anti-patterns.md

@@ -38,6 +38,7 @@ connection until an RPC is executed. Instead of using the WithBlock option, whic
 may not be recommended in some cases, you can call the
 [`ClientConn.Connect`](https://pkg.go.dev/google.golang.org/grpc#ClientConn.Connect)
 method to explicitly initiate a connection.
+[`WithBlock`](https://pkg.go.dev/google.golang.org/grpc#WithBlock) in an instance where WithBlock(true) is used, `Connect` and `WaitForStateChange` is invoked until either the context created via `context.WithTimeout` expires or the `ClientConn` is ready.
 
 ### Using `FailOnNonTempDialError`, `WithBlock`, and `WithReturnConnectionError`
 
@@ -56,6 +57,17 @@ created and then immediately lost.  Implementing proper error handling for RPCs
 is crucial for maintaining the reliability and stability of your gRPC
 communication.
 
+### Difference between Dial and NewClient
+[`grpc.NewClient`](https://pkg.go.dev/google.golang.org/grpc#NewClient) is a function in the grpc libaray that creates a new gRPC `channel` for the target URI that is passed in as an argument, together with a list of `DialOption`, and returns [`ClientConn`](https://pkg.go.dev/google.golang.org/grpc#ClientConn) an object representing a server connection.
+
+Unlike `grpc.NewClient`, whereby using the ClientConn for RPCs will automatically cause it to connect or `Connect` may be used to manually create a connection, by default `Dial` does not always establish a connection to servers. Connection behavior is determined by the load balancing policy used.
+
+`grpc.NewClient` automatically ignores `DialOptions` returned by `WithBlock`, `WithTimeout`, `WithReturnConnectionError`, and `FailOnNonTempDialError. 
+
+`grpc.NewClient` uses passthrough as the default name resolver for backward compatibility while  `Dial` uses dns as its default name resolver. This subtle diffrence is crucial in legacy systems that specify a custom dialer and expect it to receive the target string directly.
+
+Timeouts are not supported by `grpc.NewClient`. 
+
 ###  Why we discourage using `FailOnNonTempDialError`, `WithBlock`, and `WithReturnConnectionError`
 
 When a client attempts to connect to a gRPC server, it can encounter a variety

authz/audit/audit_logging_test.go

@@ -279,9 +279,9 @@ func (s) TestAuditLogger(t *testing.T) {
 			go s.Serve(lis)
 
 			// Setup gRPC test client with certificates containing a SPIFFE Id.
-			clientConn, err := grpc.Dial(lis.Addr().String(), grpc.WithTransportCredentials(clientCreds))
+			clientConn, err := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(clientCreds))
 			if err != nil {
-				t.Fatalf("grpc.Dial(%v) failed: %v", lis.Addr().String(), err)
+				t.Fatalf("grpc.NewClient(%v) failed: %v", lis.Addr().String(), err)
 			}
 			defer clientConn.Close()
 			client := testgrpc.NewTestServiceClient(clientConn)

authz/grpc_authz_end2end_test.go

@@ -326,9 +326,9 @@ func (s) TestStaticPolicyEnd2End(t *testing.T) {
 			go s.Serve(lis)
 
 			// Establish a connection to the server.
-			clientConn, err := grpc.Dial(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
+			clientConn, err := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
 			if err != nil {
-				t.Fatalf("grpc.Dial(%v) failed: %v", lis.Addr().String(), err)
+				t.Fatalf("grpc.NewClient(%v) failed: %v", lis.Addr().String(), err)
 			}
 			defer clientConn.Close()
 			client := testgrpc.NewTestServiceClient(clientConn)
@@ -400,9 +400,9 @@ func (s) TestAllowsRPCRequestWithPrincipalsFieldOnTLSAuthenticatedConnection(t *
 	if err != nil {
 		t.Fatalf("failed to load credentials: %v", err)
 	}
-	clientConn, err := grpc.Dial(lis.Addr().String(), grpc.WithTransportCredentials(creds))
+	clientConn, err := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(creds))
 	if err != nil {
-		t.Fatalf("grpc.Dial(%v) failed: %v", lis.Addr().String(), err)
+		t.Fatalf("grpc.NewClient(%v) failed: %v", lis.Addr().String(), err)
 	}
 	defer clientConn.Close()
 	client := testgrpc.NewTestServiceClient(clientConn)
@@ -478,9 +478,9 @@ func (s) TestAllowsRPCRequestWithPrincipalsFieldOnMTLSAuthenticatedConnection(t
 		RootCAs:      roots,
 		ServerName:   "x.test.example.com",
 	})
-	clientConn, err := grpc.Dial(lis.Addr().String(), grpc.WithTransportCredentials(creds))
+	clientConn, err := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(creds))
 	if err != nil {
-		t.Fatalf("grpc.Dial(%v) failed: %v", lis.Addr().String(), err)
+		t.Fatalf("grpc.NewClient(%v) failed: %v", lis.Addr().String(), err)
 	}
 	defer clientConn.Close()
 	client := testgrpc.NewTestServiceClient(clientConn)
@@ -516,9 +516,9 @@ func (s) TestFileWatcherEnd2End(t *testing.T) {
 			go s.Serve(lis)
 
 			// Establish a connection to the server.
-			clientConn, err := grpc.Dial(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
+			clientConn, err := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
 			if err != nil {
-				t.Fatalf("grpc.Dial(%v) failed: %v", lis.Addr().String(), err)
+				t.Fatalf("grpc.NewClient(%v) failed: %v", lis.Addr().String(), err)
 			}
 			defer clientConn.Close()
 			client := testgrpc.NewTestServiceClient(clientConn)
@@ -585,9 +585,9 @@ func (s) TestFileWatcher_ValidPolicyRefresh(t *testing.T) {
 	go s.Serve(lis)
 
 	// Establish a connection to the server.
-	clientConn, err := grpc.Dial(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
+	clientConn, err := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
-		t.Fatalf("grpc.Dial(%v) failed: %v", lis.Addr().String(), err)
+		t.Fatalf("grpc.NewClient(%v) failed: %v", lis.Addr().String(), err)
 	}
 	defer clientConn.Close()
 	client := testgrpc.NewTestServiceClient(clientConn)
@@ -633,9 +633,9 @@ func (s) TestFileWatcher_InvalidPolicySkipReload(t *testing.T) {
 	go s.Serve(lis)
 
 	// Establish a connection to the server.
-	clientConn, err := grpc.Dial(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
+	clientConn, err := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
-		t.Fatalf("grpc.Dial(%v) failed: %v", lis.Addr().String(), err)
+		t.Fatalf("grpc.NewClient(%v) failed: %v", lis.Addr().String(), err)
 	}
 	defer clientConn.Close()
 	client := testgrpc.NewTestServiceClient(clientConn)
@@ -684,9 +684,9 @@ func (s) TestFileWatcher_RecoversFromReloadFailure(t *testing.T) {
 	go s.Serve(lis)
 
 	// Establish a connection to the server.
-	clientConn, err := grpc.Dial(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
+	clientConn, err := grpc.NewClient(lis.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
-		t.Fatalf("grpc.Dial(%v) failed: %v", lis.Addr().String(), err)
+		t.Fatalf("grpc.NewClient(%v) failed: %v", lis.Addr().String(), err)
 	}
 	defer clientConn.Close()
 	client := testgrpc.NewTestServiceClient(clientConn)

balancer/grpclb/grpclb_test.go

@@ -458,7 +458,7 @@ func (s) TestGRPCLB_Basic(t *testing.T) {
 		grpc.WithContextDialer(fakeNameDialer),
 		grpc.WithUserAgent(testUserAgent),
 	}
-	cc, err := grpc.Dial(r.Scheme()+":///"+beServerName, dopts...)
+	cc, err := grpc.NewClient(r.Scheme()+":///"+beServerName, dopts...)
 	if err != nil {
 		t.Fatalf("Failed to dial to the backend %v", err)
 	}
@@ -515,7 +515,7 @@ func (s) TestGRPCLB_Weighted(t *testing.T) {
 		grpc.WithTransportCredentials(&serverNameCheckCreds{}),
 		grpc.WithContextDialer(fakeNameDialer),
 	}
-	cc, err := grpc.Dial(r.Scheme()+":///"+beServerName, dopts...)
+	cc, err := grpc.NewClient(r.Scheme()+":///"+beServerName, dopts...)
 	if err != nil {
 		t.Fatalf("Failed to dial to the backend %v", err)
 	}
@@ -595,7 +595,7 @@ func (s) TestGRPCLB_DropRequest(t *testing.T) {
 		grpc.WithTransportCredentials(&serverNameCheckCreds{}),
 		grpc.WithContextDialer(fakeNameDialer),
 	}
-	cc, err := grpc.Dial(r.Scheme()+":///"+beServerName, dopts...)
+	cc, err := grpc.NewClient(r.Scheme()+":///"+beServerName, dopts...)
 	if err != nil {
 		t.Fatalf("Failed to dial to the backend %v", err)
 	}
@@ -767,7 +767,7 @@ func (s) TestGRPCLB_BalancerDisconnects(t *testing.T) {
 		grpc.WithTransportCredentials(&serverNameCheckCreds{}),
 		grpc.WithContextDialer(fakeNameDialer),
 	}
-	cc, err := grpc.Dial(r.Scheme()+":///"+beServerName, dopts...)
+	cc, err := grpc.NewClient(r.Scheme()+":///"+beServerName, dopts...)
 	if err != nil {
 		t.Fatalf("Failed to dial to the backend %v", err)
 	}
@@ -938,7 +938,7 @@ func (s) TestGRPCLB_ExplicitFallback(t *testing.T) {
 		grpc.WithTransportCredentials(&serverNameCheckCreds{}),
 		grpc.WithContextDialer(fakeNameDialer),
 	}
-	cc, err := grpc.Dial(r.Scheme()+":///"+beServerName, dopts...)
+	cc, err := grpc.NewClient(r.Scheme()+":///"+beServerName, dopts...)
 	if err != nil {
 		t.Fatalf("Failed to dial to the backend %v", err)
 	}

balancer/leastrequest/balancer_test.go

@@ -232,9 +232,9 @@ func (s) TestLeastRequestE2E(t *testing.T) {
 		ServiceConfig: sc,
 	})
 
-	cc, err := grpc.Dial(mr.Scheme()+":///", grpc.WithResolvers(mr), grpc.WithTransportCredentials(insecure.NewCredentials()))
+	cc, err := grpc.NewClient(mr.Scheme()+":///", grpc.WithResolvers(mr), grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
-		t.Fatalf("grpc.Dial() failed: %v", err)
+		t.Fatalf("grpc.NewClient() failed: %v", err)
 	}
 	defer cc.Close()
 	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
@@ -347,9 +347,9 @@ func (s) TestLeastRequestPersistsCounts(t *testing.T) {
 		ServiceConfig: sc,
 	})
 
-	cc, err := grpc.Dial(mr.Scheme()+":///", grpc.WithResolvers(mr), grpc.WithTransportCredentials(insecure.NewCredentials()))
+	cc, err := grpc.NewClient(mr.Scheme()+":///", grpc.WithResolvers(mr), grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
-		t.Fatalf("grpc.Dial() failed: %v", err)
+		t.Fatalf("grpc.NewClient() failed: %v", err)
 	}
 	defer cc.Close()
 	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)
@@ -488,9 +488,9 @@ func (s) TestConcurrentRPCs(t *testing.T) {
 		ServiceConfig: sc,
 	})
 
-	cc, err := grpc.Dial(mr.Scheme()+":///", grpc.WithResolvers(mr), grpc.WithTransportCredentials(insecure.NewCredentials()))
+	cc, err := grpc.NewClient(mr.Scheme()+":///", grpc.WithResolvers(mr), grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
-		t.Fatalf("grpc.Dial() failed: %v", err)
+		t.Fatalf("grpc.NewClient() failed: %v", err)
 	}
 	defer cc.Close()
 	ctx, cancel := context.WithTimeout(context.Background(), defaultTestTimeout)

binarylog/binarylog_end2end_test.go

@@ -316,7 +316,7 @@ func (te *test) clientConn() *grpc.ClientConn {
 	opts := []grpc.DialOption{grpc.WithTransportCredentials(insecure.NewCredentials()), grpc.WithBlock()}
 
 	var err error
-	te.cc, err = grpc.Dial(te.srvAddr, opts...)
+	te.cc, err = grpc.NewClient(te.srvAddr, opts...)
 	if err != nil {
 		te.t.Fatalf("Dial(%q) = %v", te.srvAddr, err)
 	}

clientconn_authority_test.go

@@ -128,8 +128,8 @@ func (s) TestClientConnAuthority_CredsAndDialOptionMismatch(t *testing.T) {
 		t.Fatalf("credentials.NewClientTLSFromFile(_, %q) failed: %v", err, serverNameOverride)
 	}
 	opts := []DialOption{WithTransportCredentials(creds), WithAuthority("authority-override")}
-	if cc, err := Dial("Non-Existent.Server:8000", opts...); err == nil {
+	if cc, err := NewClient("Non-Existent.Server:8000", opts...); err == nil {
 		cc.Close()
-		t.Fatal("grpc.Dial() succeeded when expected to fail")
+		t.Fatal("grpc.NewClient() succeeded when expected to fail")
 	}
 }

credentials/alts/alts_test.go

@@ -385,9 +385,9 @@ func versions(minMajor, minMinor, maxMajor, maxMinor uint32) *altspb.RpcProtocol
 
 func establishAltsConnection(t *testing.T, handshakerAddress, serverAddress string) {
 	clientCreds := NewClientCreds(&ClientOptions{HandshakerServiceAddress: handshakerAddress})
-	conn, err := grpc.Dial(serverAddress, grpc.WithTransportCredentials(clientCreds))
+	conn, err := grpc.NewClient(serverAddress, grpc.WithTransportCredentials(clientCreds))
 	if err != nil {
-		t.Fatalf("grpc.Dial(%v) failed: %v", serverAddress, err)
+		t.Fatalf("grpc.NewClient(%v) failed: %v", serverAddress, err)
 	}
 	defer conn.Close()
 	ctx, cancel := context.WithTimeout(context.Background(), defaultTestLongTimeout)

credentials/tls_ext_test.go

@@ -103,9 +103,9 @@ func (s) TestTLS_MinVersion12(t *testing.T) {
 	}
 	defer ss.Stop()
 
-	cc, err := grpc.Dial(ss.Address, grpc.WithTransportCredentials(clientCreds))
+	cc, err := grpc.NewClient(ss.Address, grpc.WithTransportCredentials(clientCreds))
 	if err != nil {
-		t.Fatalf("grpc.Dial error: %v", err)
+		t.Fatalf("grpc.NewClient error: %v", err)
 	}
 	defer cc.Close()
 
@@ -189,9 +189,9 @@ func (s) TestTLS_CipherSuites(t *testing.T) {
 	}
 	defer ss.Stop()
 
-	cc, err := grpc.Dial("dns:"+ss.Address, grpc.WithTransportCredentials(clientCreds))
+	cc, err := grpc.NewClient("dns:"+ss.Address, grpc.WithTransportCredentials(clientCreds))
 	if err != nil {
-		t.Fatalf("grpc.Dial error: %v", err)
+		t.Fatalf("grpc.NewClient error: %v", err)
 	}
 	defer cc.Close()
 

encoding/encoding_test.go

@@ -122,7 +122,7 @@ func (s) TestEncodeDoesntPanicOnServer(t *testing.T) {
 	defer backend.Stop()
 
 	// Create a channel to the above server.
-	cc, err := grpc.Dial(backend.Address, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	cc, err := grpc.NewClient(backend.Address, grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
 		t.Fatalf("Failed to dial test backend at %q: %v", backend.Address, err)
 	}
@@ -159,7 +159,7 @@ func (s) TestDecodeDoesntPanicOnServer(t *testing.T) {
 
 	// Create a channel to the above server. Since we do not specify any codec
 	// here, the proto codec will get automatically used.
-	cc, err := grpc.Dial(backend.Address, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	cc, err := grpc.NewClient(backend.Address, grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
 		t.Fatalf("Failed to dial test backend at %q: %v", backend.Address, err)
 	}
@@ -196,7 +196,7 @@ func (s) TestEncodeDoesntPanicOnClient(t *testing.T) {
 	ec := &errProtoCodec{name: t.Name(), encodingErr: encodingErr}
 
 	// Create a channel to the above server.
-	cc, err := grpc.Dial(backend.Address, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	cc, err := grpc.NewClient(backend.Address, grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
 		t.Fatalf("Failed to dial test backend at %q: %v", backend.Address, err)
 	}
@@ -232,7 +232,7 @@ func (s) TestDecodeDoesntPanicOnClient(t *testing.T) {
 	ec := &errProtoCodec{name: t.Name(), decodingErr: decodingErr}
 
 	// Create a channel to the above server.
-	cc, err := grpc.Dial(backend.Address, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	cc, err := grpc.NewClient(backend.Address, grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
 		t.Fatalf("Failed to dial test backend at %q: %v", backend.Address, err)
 	}
@@ -288,7 +288,7 @@ func (s) TestForceServerCodec(t *testing.T) {
 	defer backend.Stop()
 
 	// Create a channel to the above server.
-	cc, err := grpc.Dial(backend.Address, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	cc, err := grpc.NewClient(backend.Address, grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
 		t.Fatalf("Failed to dial test backend at %q: %v", backend.Address, err)
 	}

examples/features/authentication/client/main.go

@@ -66,7 +66,7 @@ func main() {
 		grpc.WithTransportCredentials(creds),
 	}
 
-	conn, err := grpc.Dial(*addr, opts...)
+	conn, err := grpc.NewClient(*addr, opts...)
 	if err != nil {
 		log.Fatalf("did not connect: %v", err)
 	}

examples/features/authz/client/main.go

@@ -99,9 +99,9 @@ func main() {
 		log.Fatalf("failed to load credentials: %v", err)
 	}
 	// Set up a connection to the server.
-	conn, err := grpc.Dial(*addr, grpc.WithTransportCredentials(creds))
+	conn, err := grpc.NewClient(*addr, grpc.WithTransportCredentials(creds))
 	if err != nil {
-		log.Fatalf("grpc.Dial(%q): %v", *addr, err)
+		log.Fatalf("grpc.NewClient(%q): %v", *addr, err)
 	}
 	defer conn.Close()
 

examples/features/cancellation/client/main.go

@@ -56,7 +56,7 @@ func main() {
 	flag.Parse()
 
 	// Set up a connection to the server.
-	conn, err := grpc.Dial(*addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	conn, err := grpc.NewClient(*addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
 		log.Fatalf("did not connect: %v", err)
 	}

examples/features/compression/client/main.go

@@ -38,7 +38,7 @@ func main() {
 	flag.Parse()
 
 	// Set up a connection to the server.
-	conn, err := grpc.Dial(*addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	conn, err := grpc.NewClient(*addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
 		log.Fatalf("did not connect: %v", err)
 	}

examples/features/deadline/client/main.go

@@ -73,7 +73,7 @@ func streamingCall(c pb.EchoClient, requestID int, message string, want codes.Co
 func main() {
 	flag.Parse()
 
-	conn, err := grpc.Dial(*addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	conn, err := grpc.NewClient(*addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
 		log.Fatalf("did not connect: %v", err)
 	}

examples/features/deadline/server/main.go

@@ -95,7 +95,7 @@ func (s *server) Close() {
 
 func newEchoServer() *server {
 	target := fmt.Sprintf("localhost:%v", *port)
-	cc, err := grpc.Dial(target, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	cc, err := grpc.NewClient(target, grpc.WithTransportCredentials(insecure.NewCredentials()))
 	if err != nil {
 		log.Fatalf("did not connect: %v", err)
 	}

examples/features/debugging/client/main.go

@@ -60,7 +60,7 @@ func main() {
 	/***** Initialize manual resolver and Dial *****/
 	r := manual.NewBuilderWithScheme("whatever")
 	// Set up a connection to the server.
-	conn, err := grpc.Dial(r.Scheme()+":///test.server", grpc.WithTransportCredentials(insecure.NewCredentials()), grpc.WithResolvers(r), grpc.WithDefaultServiceConfig(`{"loadBalancingPolicy":"round_robin"}`))
+	conn, err := grpc.NewClient(r.Scheme()+":///test.server", grpc.WithTransportCredentials(insecure.NewCredentials()), grpc.WithResolvers(r), grpc.WithDefaultServiceConfig(`{"loadBalancingPolicy":"round_robin"}`))
 	if err != nil {
 		log.Fatalf("did not connect: %v", err)
 	}

examples/features/encryption/ALTS/client/main.go

@@ -50,7 +50,7 @@ func main() {
 	altsTC := alts.NewClientCreds(alts.DefaultClientOptions())
 
 	// Set up a connection to the server.
-	conn, err := grpc.Dial(*addr, grpc.WithTransportCredentials(altsTC))
+	conn, err := grpc.NewClient(*addr, grpc.WithTransportCredentials(altsTC))
 	if err != nil {
 		log.Fatalf("did not connect: %v", err)
 	}

examples/features/encryption/TLS/client/main.go

@@ -54,7 +54,7 @@ func main() {
 	}
 
 	// Set up a connection to the server.
-	conn, err := grpc.Dial(*addr, grpc.WithTransportCredentials(creds))
+	conn, err := grpc.NewClient(*addr, grpc.WithTransportCredentials(creds))
 	if err != nil {
 		log.Fatalf("did not connect: %v", err)
 	}

examples/features/encryption/mTLS/client/main.go

@@ -71,7 +71,7 @@ func main() {
 		RootCAs:      ca,
 	}
 
-	conn, err := grpc.Dial(*addr, grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)))
+	conn, err := grpc.NewClient(*addr, grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)))
 	if err != nil {
 		log.Fatalf("did not connect: %v", err)
 	}