feat(spanner): add tpc support (#2333)

Author: alkatrivedi

src/index.ts

@@ -156,6 +156,17 @@ export interface SpannerOptions extends GrpcClientOptions {
   defaultTransactionOptions?: Pick<RunTransactionOptions, 'isolationLevel'>;
   observabilityOptions?: ObservabilityOptions;
   interceptors?: any[];
+  /**
+   * The Trusted Cloud Domain (TPC) DNS of the service used to make requests.
+   * Defaults to `googleapis.com`.
+   * We support both camelCase and snake_case for the universe domain.
+   * Customer may set any of these as both the options are same,
+   * they both points to universe endpoint.
+   * There is no preference for any of these option; however exception will be
+   * thrown if both are set to different values.
+   */
+  universe_domain?: string;
+  universeDomain?: string;
 }
 export interface RequestConfig {
   client: string;
@@ -206,6 +217,45 @@ export type TranslateEnumKeys<
   [P in keyof T]: P extends U ? EnumKey<E> | null | undefined : T[P];
 };
 
+/**
+ * Retrieves the universe domain.
+ *
+ * This function checks for a universe domain in the following order:
+ * 1. The `universeDomain` property within the provided spanner options.
+ * 2. The `universe_domain` property within the provided spanner options.
+ * 3. The `GOOGLE_CLOUD_UNIVERSE_DOMAIN` environment variable.
+ * 4. If none of the above properties will be set, it will fallback to `googleapis.com`.
+ *
+ * For consistency with the Auth client, if the `universe_domain` option or the
+ * `GOOGLE_CLOUD_UNIVERSE_DOMAIN` env variable is used, this function will also set the
+ * `universeDomain` property within the provided `SpannerOptions` object. This ensures the
+ * Spanner client's universe domain aligns with the universe configured for authentication.
+ *
+ * @param {SpannerOptions} options - The Spanner client options.
+ * @returns {string} The universe domain.
+ */
+function getUniverseDomain(options: SpannerOptions): string {
+  const universeDomainEnvVar =
+    typeof process === 'object' && typeof process.env === 'object'
+      ? process.env['GOOGLE_CLOUD_UNIVERSE_DOMAIN']
+      : undefined;
+  const universeDomain =
+    options?.universeDomain ??
+    options?.universe_domain ??
+    universeDomainEnvVar ??
+    'googleapis.com';
+  // if the options.universe_domain/GOOGLE_CLOUD_UNIVERSE_DOMAIN env variable is set,
+  // set its value to the Spanner `universeDomain` options
+  // to match it with the universe from Auth Client
+  if (
+    !options?.universeDomain &&
+    (options?.universe_domain || process.env.GOOGLE_CLOUD_UNIVERSE_DOMAIN)
+  ) {
+    options.universeDomain = universeDomain;
+  }
+  return universeDomain;
+}
+
 /**
  * [Cloud Spanner](https://cloud.google.com/spanner) is a highly scalable,
  * transactional, managed, NewSQL database service. Cloud Spanner solves the
@@ -259,6 +309,7 @@ class Spanner extends GrpcService {
   directedReadOptions: google.spanner.v1.IDirectedReadOptions | null;
   defaultTransactionOptions: RunTransactionOptions;
   _observabilityOptions: ObservabilityOptions | undefined;
+  private _universeDomain: string;
   readonly _nthClientId: number;
 
   /**
@@ -351,6 +402,16 @@ class Spanner extends GrpcService {
         };
     delete options.defaultTransactionOptions;
 
+    if (
+      options?.universe_domain &&
+      options?.universeDomain &&
+      options?.universe_domain !== options?.universeDomain
+    ) {
+      throw new Error(
+        'Please set either universe_domain or universeDomain, but not both.',
+      );
+    }
+
     const emulatorHost = Spanner.getSpannerEmulatorHost();
     if (
       emulatorHost &&
@@ -361,12 +422,12 @@ class Spanner extends GrpcService {
       options.port = emulatorHost.port;
       options.sslCreds = grpc.credentials.createInsecure();
     }
+
+    const universeEndpoint = getUniverseDomain(options);
+    const spannerUniverseEndpoint = 'spanner.' + universeEndpoint;
     const config = {
       baseUrl:
-        options.apiEndpoint ||
-        options.servicePath ||
-        // TODO: for TPC, this needs to support universeDomain
-        'spanner.googleapis.com',
+        options.apiEndpoint || options.servicePath || spannerUniverseEndpoint,
       protosDir: path.resolve(__dirname, '../protos'),
       protoServices: {
         Operations: {
@@ -399,6 +460,11 @@ class Spanner extends GrpcService {
     );
     ensureInitialContextManagerSet();
     this._nthClientId = nextSpannerClientId();
+    this._universeDomain = universeEndpoint;
+  }
+
+  get universeDomain() {
+    return this._universeDomain;
   }
 
   /**

system-test/tpc-test.ts

@@ -0,0 +1,126 @@
+// Copyright 2025 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
+//
+//     https://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.
+
+import {describe, it} from 'mocha';
+import {MutationSet, Spanner} from '../src';
+import * as assert from 'assert';
+
+// INSTRUCTIONS FOR RUNNING TEST:
+// 1. Change describe.skip to describe.only below.
+// 2. Reassign process.env.GOOGLE_APPLICATION_CREDENTIALS to local key file.
+// 3. Reassign UNIVERSE_DOMAIN_CONSTANT to the universe domain to test.
+// 4. Run `npm run system-test`.
+
+describe.skip('Universe domain tests', () => {
+  // These tests are only designed to pass when using the service account
+  // credentials for the universe domain environment so we skip them in the CI pipeline.
+
+  before(() => {
+    process.env.GOOGLE_APPLICATION_CREDENTIALS = 'path to your credential file';
+  });
+
+  async function runTest(spanner: Spanner, instanceId, databaseId) {
+    const instance = spanner.instance(instanceId);
+    const database = instance.database(databaseId);
+    const tableName = 'VenueDetails';
+    const table = database.table(tableName);
+
+    const schema = `CREATE TABLE ${tableName} (
+                VenueId                INT64 NOT NULL,
+                VenueName              STRING(100),
+                Capacity               INT64,
+            ) PRIMARY KEY (VenueId)`;
+
+    console.log(`Creating table ${table.name}`);
+    const [, operation] = await table.create(schema);
+
+    await operation.promise();
+
+    console.log(`${table.name} create successfully.`);
+
+    const venuesTable = database.table(tableName);
+    console.log(`Inserting data into the table ${table.name}`);
+    await venuesTable.insert([
+      {VenueId: 1, VenueName: 'Marc', Capacity: 100},
+      {VenueId: 2, VenueName: 'Marc', Capacity: 200},
+    ]);
+
+    const mutations = new MutationSet();
+
+    mutations.insert(tableName, {
+      VenueId: '3',
+      VenueName: 'Marc',
+      Capacity: 700,
+    });
+    mutations.insert(tableName, {
+      VenueId: '4',
+      VenueName: 'Marc',
+      Capacity: 800,
+    });
+    mutations.update(tableName, {
+      VenueId: '3',
+      VenueName: 'Marc',
+      Capacity: 300,
+    });
+    mutations.update(tableName, {
+      VenueId: '4',
+      VenueName: 'Marc',
+      Capacity: 400,
+    });
+
+    await database.writeAtLeastOnce(mutations);
+
+    const query = {
+      columns: ['VenueId', 'VenueName', 'Capacity'],
+      keySet: {
+        all: true,
+      },
+    };
+
+    const [rows] = await venuesTable.read(query);
+
+    console.log(`Inserted ${rows.length} rows into the table ${table.name}`);
+
+    console.log(`Reading rows in the table ${table.name}`);
+
+    rows.forEach(row => {
+      const json = row.toJSON();
+      console.log(
+        `VenueId: ${json.VenueId}, VenueName: ${json.VenueName}, Capacity: ${json.Capacity}`,
+      );
+    });
+
+    console.log(`deleting table ${table.name}`);
+    await table.delete();
+    console.log(`deleted table ${table.name}`);
+  }
+  it('should be able to run apis successfully against TPC environment', async () => {
+    const UNIVERSE_DOMAIN_CONSTANT = 'my-universe-domain';
+    const projectId = 'tpc-project-id';
+    const universeDomain = UNIVERSE_DOMAIN_CONSTANT;
+    const options = {
+      projectId,
+      universeDomain,
+    };
+    const spanner = new Spanner(options);
+    const instanceId = 'your-test-instance-id';
+    const databaseId = 'your-test-database-id';
+
+    try {
+      await runTest(spanner, instanceId, databaseId);
+    } catch (e) {
+      assert.ifError(e);
+    }
+  });
+});

test/index.ts

@@ -434,6 +434,104 @@ describe('Spanner', () => {
     });
   });
 
+  describe('TPC tests', () => {
+    const UNIVERSE_DOMAIN_CONSTANT = 'fake-universe-domain';
+
+    it('should have default universe domain set to `googleapis.com`', () => {
+      try {
+        const spanner = new Spanner();
+        // get default universe domain from spanner object when
+        // neither of univserDomain and universe_domain are set
+        // nor env GOOGLE_CLOUD_UNIVERSE_DOMAIN is set
+        assert.strictEqual(spanner.universeDomain, 'googleapis.com');
+        // GoogleAuthOption's univserseDomain property must be undefined here
+        // as it will get configure to default value in the gax library
+        // please see: https://github.com/googleapis/gax-nodejs/blob/de43edd3524b7f995bd3cf5c34ddead03828b546/gax/src/grpc.ts#L431
+        assert.strictEqual(spanner.options.universeDomain, undefined);
+      } catch (err) {
+        assert.ifError(err);
+      }
+    });
+
+    it('should optionally accept universeDomain', () => {
+      const fakeOption = {
+        universeDomain: UNIVERSE_DOMAIN_CONSTANT,
+      };
+
+      try {
+        const spanner = new Spanner(fakeOption);
+        // get universe domain from spanner object
+        assert.strictEqual(spanner.universeDomain, fakeOption.universeDomain);
+        // GoogleAuthOption's univserseDomain property must be set
+        // to match it with the universe from Auth Client
+        assert.strictEqual(
+          spanner.options.universeDomain,
+          fakeOption.universeDomain,
+        );
+      } catch (err) {
+        assert.ifError(err);
+      }
+    });
+
+    it('should optionally accept universe_domain', () => {
+      const fakeOption = {
+        universe_domain: UNIVERSE_DOMAIN_CONSTANT,
+      };
+
+      try {
+        const spanner = new Spanner(fakeOption);
+        // get universe domain from spanner object
+        assert.strictEqual(spanner.universeDomain, fakeOption.universe_domain);
+        // GoogleAuthOption's univserseDomain property must be set
+        // to match it with the universe from Auth Client
+        assert.strictEqual(
+          spanner.options.universeDomain,
+          fakeOption.universe_domain,
+        );
+      } catch (err) {
+        assert.ifError(err);
+      }
+    });
+
+    it('should set universe domain upon setting env GOOGLE_CLOUD_UNIVERSE_DOMAIN', () => {
+      process.env.GOOGLE_CLOUD_UNIVERSE_DOMAIN = UNIVERSE_DOMAIN_CONSTANT;
+
+      try {
+        const spanner = new Spanner();
+        // get universe domain from spanner object
+        assert.strictEqual(spanner.universeDomain, UNIVERSE_DOMAIN_CONSTANT);
+        // GoogleAuthOption's univserseDomain property must be set
+        // to match it with the universe from Auth Client
+        assert.strictEqual(
+          spanner.options.universeDomain,
+          UNIVERSE_DOMAIN_CONSTANT,
+        );
+      } catch (err) {
+        assert.ifError(err);
+      }
+      delete process.env.GOOGLE_CLOUD_UNIVERSE_DOMAIN;
+    });
+
+    it('should throw an error if universe_domain and universeDomain both are set to different values', () => {
+      const fakeOption = {
+        universeDomain: 'fake-universe-domain-1',
+        universe_domain: 'fake-universe-domain-2',
+      };
+      const fakeError = new Error(
+        'Please set either universe_domain or universeDomain, but not both.',
+      );
+
+      try {
+        const spanner = new Spanner(fakeOption);
+        // this line should never reach client must throw an error.
+        throw new Error('should never reach this line');
+      } catch (err) {
+        assert.deepStrictEqual(err, fakeError);
+      }
+      delete process.env.GOOGLE_CLOUD_UNIVERSE_DOMAIN;
+    });
+  });
+
   describe('date', () => {
     it('should create a default SpannerDate instance', () => {
       const customValue = {};