feat: add support for spanner client resource base routing

src/index.ts

@@ -35,7 +35,7 @@ import {SessionPool} from './session-pool';
 import {Table} from './table';
 import {PartitionedDml, Snapshot, Transaction} from './transaction';
 import {GrpcClientOptions} from 'google-gax';
-import {ChannelCredentials} from 'grpc';
+import {ChannelCredentials, status} from 'grpc';
 import {
   createGcpApiConfig,
   gcpCallInvocationTransformer,
@@ -793,7 +793,7 @@ class Spanner extends GrpcService {
   }
 
   /**
-   * get GAX client. This will retrive the end point uris for specific instance and cache the client accordingly.
+   * get GAX client. This will retrieve the end point uris for specific instance and cache the client accordingly.
    *
    * @private
    *
@@ -830,10 +830,15 @@ class Spanner extends GrpcService {
         },
         (err, instance) => {
           if (err) {
-            if (err.code === 7) {
-              process.emitWarning(
-                'spanner.instances.get permission must be added to use resource based routing.'
-              );
+            const PERMISSION_DENIED_MESSAGE = `The client library attempted to connect to 
+an endpoint closer to your Cloud Spanner data but was unable to 
+do so. The client library will fallback to the API endpoint given 
+in the client options, which may result in increased latency.
+We recommend including the scope 
+https://www.googleapis.com/auth/spanner.admin 
+so that the client library can get an instance-specific endpoint and efficiently route requests.`;
+            if (err.code === status.PERMISSION_DENIED) {
+              process.emitWarning(PERMISSION_DENIED_MESSAGE);
               this.setSpannerClient(clientName, config, this.options);
               callback(null, this.clients_.get(clientName)!);
               return;
@@ -855,11 +860,11 @@ class Spanner extends GrpcService {
     }
   }
   /**
-   * cache the GAX client accordingly.
+   * Cache the GAX client accordingly.
    *
    * @private
    *
-   * @param {string} clientName client name to cache.
+   * @param {string} clientName Client name to cache.
    * @param {object} config Request config
    * @param {object} options Spanner options
    */

test/index.ts

@@ -966,7 +966,7 @@ describe('Spanner', () => {
       spanner.prepareGapicRequest_(CONFIG, assert.ifError);
     });
 
-    it('should return an error from get instance endpointUris', done => {
+    it('should return an error from get instance endpointUris.', done => {
       const error = new Error('Error.') as ServiceError;
       const instanceId = 'instance-id';
       spanner.options.enableResourceBasedRouting = true;
@@ -982,11 +982,15 @@ describe('Spanner', () => {
       });
     });
 
-    it('should continue if do not have permission for instance', done => {
+    it('should continue if a permission error is returned for the instance.', done => {
+      const PERMISSION_DENIED_MESSAGE = `The client library attempted to connect to 
+an endpoint closer to your Cloud Spanner data but was unable to 
+do so. The client library will fallback to the API endpoint given 
+in the client options, which may result in increased latency.
+We recommend including the scope 
+https://www.googleapis.com/auth/spanner.admin 
+so that the client library can get an instance-specific endpoint and efficiently route requests.`;
       sandbox.stub(process, 'emitWarning');
-      const expectedWarning =
-        'spanner.instances.get permission must be added to use resource based routing.';
-
       const error = new Error('Error.') as ServiceError;
       error.code = 7;
       const instanceId = 'instance-id';
@@ -1000,13 +1004,15 @@ describe('Spanner', () => {
       spanner.prepareGapicRequest_(CONFIG, err => {
         assert.ifError(err);
         assert.ok(
-          (process.emitWarning as sinon.SinonStub).calledWith(expectedWarning)
+          (process.emitWarning as sinon.SinonStub).calledWith(
+            PERMISSION_DENIED_MESSAGE
+          )
         );
         done();
       });
     });
 
-    it('should return an error if instanceId does not provided.', done => {
+    it('should return an error if instanceId is not provided.', done => {
       spanner.options.enableResourceBasedRouting = true;
 
       spanner.prepareGapicRequest_(CONFIG, err => {
@@ -1041,12 +1047,12 @@ describe('Spanner', () => {
 
     it('should use user-specified endpoint when GetInstance response is empty.', done => {
       const instanceId = 'instance-id';
-      const customeEndpoint = 'us-central1-spanner.googleapis.com';
+      const customEndpoint = 'us-central1-spanner.googleapis.com';
       asAny(CONFIG).instanceId = instanceId;
       spanner.options.enableResourceBasedRouting = true;
 
       asAny(spanner).instance(instanceId).getMetadata = (options, callback) => {
-        asAny(spanner.options).apiEndpoint = customeEndpoint;
+        asAny(spanner.options).apiEndpoint = customEndpoint;
         callback!(null, {endpointUris: []});
       };
 
@@ -1063,7 +1069,7 @@ describe('Spanner', () => {
       spanner.prepareGapicRequest_(CONFIG, assert.ifError);
     });
 
-    it('should override the first endpoint while multiple endpointUri available.', done => {
+    it('should override the first endpoint while multiple endpointUris are available.', done => {
       const GOOGLE_CLOUD_ENABLE_RESOURCE_BASED_ROUTING =
         process.env.GOOGLE_CLOUD_ENABLE_RESOURCE_BASED_ROUTING;
       process.env.GOOGLE_CLOUD_ENABLE_RESOURCE_BASED_ROUTING = 'true';

test/spanner.ts

@@ -27,7 +27,7 @@ import * as sinon from 'sinon';
 import {google} from '../protos/protos';
 import {types} from '../src/session';
 import {ExecuteSqlRequest, RunResponse} from '../src/transaction';
-import {PartialResultStream, Row} from '../src/partial-result-stream';
+import {Row} from '../src/partial-result-stream';
 import {
   SessionLeakError,
   SessionPoolExhaustedError,
@@ -97,6 +97,7 @@ describe('Spanner with mock server', () => {
       servicePath: 'localhost',
       port,
       sslCreds: grpc.credentials.createInsecure(),
+      enableResourceBasedRouting: false, //diabled resource based routing
     });
     // Gets a reference to a Cloud Spanner instance and database
     instance = spanner.instance('instance');