feat: Allow the user to set fallback to rest (#1203)

* Allow the user to set fallback to rest

This provides a workaround for the connection issue.

* Putting together a test that mocks out gapic

Need to mock out Gapic and compare constructors

* This harness works properly

The harness mocks out the constructor and calls reach the constructor as well as the get function. So now we can see what values get passed into the constructor and get function.

* Add client testing module

Add a working test that makes sure the rest parameter gets passed down to the gapic layer.

* Regroup the code so it is better arranged

Proper describe blocks make it easier for the code to be arranged so that with and without rest tests can be incorporated into the code.

* Remove the datastore mock

Remove the datastore mock. It is not necessary.

* Add comments for test helper functions. Add tests for the non rest case.

* Clean up source code change

Make a programmatic link to the data type so that the intent is clearer.

* Add parameterized test

Parameterized tests will allow us to delete half the tests. A new type is created for the test parameters.

* Document the class for mocking datastore client

Explain the purpose of the class. This will make it useful for testing.

* Remove only

* Remove fallback params type

This type is only used once so inline it.

* Remove changes to system tests

Changes to system tests are not necessary. Remove them.

* Add header

* Check for client existence

assert resolves to falsy in tests. See if this solves the issue.

* Change it back

Add console logs and assert checks back in.

* Add more debugger logs

* Add project load logs

* console error

* Add comment for mocking out project id

This should allow the unit tests to pass in the continuous integration environment.

* linting fix

* Correct title of describe block

The title of the describe block should match the file. Remove console logs too.

* Change rest parameter in test to fallback

This parameter more specifically describes the change.

* Create a simple system test for using rest

This system test should show how the rest parameter is being used.

* Should check to see if entity is undefined

This allows the test to pass with a simple assertion check.

* Specify fallback type instead of string | undefin

Fallback type is more specific . Use it instead.

src/index.ts

@@ -97,6 +97,7 @@ export interface LongRunningCallback {
   ): void;
 }
 export type LongRunningResponse = [Operation, google.longrunning.IOperation];
+export type Fallback = boolean | 'rest' | 'proto';
 
 export interface ExportEntitiesConfig
   extends Omit<google.datastore.admin.v1.IExportEntitiesRequest, 'projectId'> {
@@ -1912,6 +1913,7 @@ export interface DatastoreOptions extends GoogleAuthOptions {
   apiEndpoint?: string;
   sslCreds?: ChannelCredentials;
   databaseId?: string;
+  fallback?: Fallback;
 }
 
 export interface KeyToLegacyUrlSafeCallback {

system-test/datastore.ts

@@ -2080,6 +2080,16 @@ async.each(
           assert.strictEqual(entities.length, 0);
         });
       });
+      describe('using the rest fallback parameter', () => {
+        it('should make a get call using rest instead of grpc', async () => {
+          const customDatastore = new Datastore({
+            fallback: 'rest',
+          });
+          const postKey = datastore.key(['Post', 'post1']);
+          const [entity] = await customDatastore.get(postKey);
+          assert.strictEqual(entity, undefined);
+        });
+      });
     });
   }
 );

test/gapic-mocks/client-initialization-testing.ts

@@ -0,0 +1,165 @@
+// Copyright 2023 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
+//
+//      http://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 {beforeEach, describe, it} from 'mocha';
+import {
+  Datastore,
+  DatastoreClient,
+  Fallback,
+  DatastoreRequest,
+  DatastoreOptions,
+} from '../../src';
+import * as assert from 'assert';
+import * as proxyquire from 'proxyquire';
+import {Callback, CallOptions} from 'google-gax';
+import * as protos from '../../protos/protos';
+import * as ds from '../../src';
+import * as mocha from 'mocha';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Any = any;
+
+const clientName = 'DatastoreClient';
+const async = require('async');
+
+/**
+ * This class mocks out the lookup function so that for tests in this file
+ * the lookup function just sends data back instead of making a call to the
+ * server. The class also saves the rest parameter in the constructor so that
+ * it can be read later for correctness.
+ *
+ */
+class FakeDatastoreClient extends DatastoreClient {
+  restParameter: Fallback;
+  constructor(...args: any[]) {
+    super();
+    this.restParameter = args[0].fallback;
+  }
+  lookup(
+    request?: protos.google.datastore.v1.ILookupRequest,
+    optionsOrCallback?:
+      | CallOptions
+      | Callback<
+          protos.google.datastore.v1.ILookupResponse,
+          protos.google.datastore.v1.ILookupRequest | null | undefined,
+          {} | null | undefined
+        >,
+    callback?: Callback<
+      protos.google.datastore.v1.ILookupResponse,
+      protos.google.datastore.v1.ILookupRequest | null | undefined,
+      {} | null | undefined
+    >
+  ): Promise<
+    [
+      protos.google.datastore.v1.ILookupResponse,
+      protos.google.datastore.v1.ILookupRequest | undefined,
+      {} | undefined,
+    ]
+  > {
+    if (callback) {
+      callback(null, {});
+    }
+    return new Promise((resolve, reject) => {
+      resolve([{}, {}, {}]);
+    });
+  }
+}
+
+describe('Client Initialization Testing', () => {
+  describe('Request', () => {
+    let Request: typeof ds.DatastoreRequest;
+    let request: Any;
+
+    /**
+     * This function is called by a test to ensure that the rest parameter
+     * gets passed to the Gapic data client's constructor
+     *
+     * @param {DatastoreRequest} [request] The request object whose data client
+     * the test makes comparisons with.
+     * @param {string | undefined} [expectedFallback] The value that the test
+     * expects the rest parameter of the data client to be equal to.
+     * @param {mocha.Done} [done] The done function used for indicating
+     * that the test is complete or that there is an error in the mocha test
+     * environment.
+     *
+     */
+    function compareRequest(
+      request: DatastoreRequest,
+      expectedFallback: Fallback,
+      done: mocha.Done
+    ) {
+      try {
+        const client = request.datastore.clients_.get(clientName);
+        assert(client);
+        assert.strictEqual(client.restParameter, expectedFallback);
+        done();
+      } catch (err: unknown) {
+        done(err);
+      }
+    }
+    async.each(
+      [
+        {
+          options: {fallback: 'rest' as Fallback},
+          expectedFallback: 'rest',
+          description: 'when specifying rest as a fallback parameter',
+        },
+        {
+          options: {},
+          expectedFallback: undefined,
+          description: 'when specifying no fallback parameter',
+        },
+      ],
+      (testParameters: {
+        options: DatastoreOptions;
+        expectedFallback: Fallback;
+        description: string;
+      }) => {
+        describe(testParameters.description, () => {
+          beforeEach(() => {
+            Request = proxyquire('../../src/request', {
+              './v1': {
+                DatastoreClient: FakeDatastoreClient,
+              },
+            }).DatastoreRequest;
+            request = new Request();
+            request.datastore = new Datastore(testParameters.options);
+            // The CI environment can't fetch project id so the function that
+            // fetches the project id needs to be mocked out.
+            request.datastore.auth.getProjectId = (
+              callback: (err: any, projectId: string) => void
+            ) => {
+              callback(null, 'some-project-id');
+            };
+          });
+          it('should set the rest parameter in the data client when calling prepareGaxRequest_', done => {
+            // This request does lazy initialization of the gapic layer Datastore client.
+            request.prepareGaxRequest_(
+              {client: clientName, method: 'lookup'},
+              () => {
+                compareRequest(request, testParameters.expectedFallback, done);
+              }
+            );
+          });
+          it('should set the rest parameter in the data client when calling request_', done => {
+            // This request does lazy initialization of the gapic layer Datastore client.
+            request.request_({client: clientName, method: 'lookup'}, () => {
+              compareRequest(request, testParameters.expectedFallback, done);
+            });
+          });
+        });
+      }
+    );
+  });
+});