feat(Bigtable): add pingAndWarm Client option (#8229)

Author: bshaffer

Bigtable/src/BigtableClient.php

@@ -25,6 +25,8 @@
 use Google\ApiCore\ValidationException;
 use Google\Auth\FetchAuthTokenInterface;
 use Google\Cloud\Bigtable\V2\Client\BigtableClient as GapicClient;
+use Google\Cloud\Bigtable\V2\PingAndWarmRequest;
+use Google\Cloud\Core\ApiHelperTrait;
 use Google\Cloud\Core\DetectProjectIdTrait;
 
 /**
@@ -44,6 +46,7 @@ class BigtableClient
     use ArrayTrait;
     use DetectProjectIdTrait;
     use ClientOptionsTrait;
+    use ApiHelperTrait;
 
     // The name of the service. Used in debug logging.
     private const SERVICE_NAME = 'google.bigtable.v2.Bigtable';
@@ -58,6 +61,23 @@ class BigtableClient
      */
     private Serializer $serializer;
 
+    /**
+     * Invoke {@see GapicClient::pingAndWarm()} when {@see self::table()} is called
+     * in order to establish a persistent gRPC channel before making an RPC call.
+     *
+     * @experimental
+     * @var bool
+     */
+    private $pingAndWarm;
+
+    /**
+     * An in-memory array to ensure pingAndWarm is only called once per instance.
+     *
+     * @experimental
+     * @var array
+     */
+    private $pingAndWarmCalled = [];
+
     /**
      * Create a Bigtable client.
      *
@@ -109,6 +129,9 @@ class BigtableClient
      *           supported options.
      *     @type string $quotaProject Specifies a user project to bill for
      *           access charges associated with the request.
+     *     @type bool $pingAndWarm EXPERIMENTAL When true, calls the
+     *           {@see GapicClient::pingAndWarm()} RPC to establish a persistent
+     *           gRPC channel before making an RPC call.
      * }
      * @throws ValidationException
      */
@@ -138,6 +161,7 @@ public function __construct(array $config = [])
 
         $this->projectId = $this->detectProjectId($detectProjectIdConfig);
         $this->serializer = new Serializer();
+        $this->pingAndWarm = $config['pingAndWarm'] ?? false;
         $this->gapicClient = new GapicClient($config);
     }
 
@@ -163,6 +187,17 @@ public function __construct(array $config = [])
      */
     public function table($instanceId, $tableId, array $options = [])
     {
+        if ($this->pingAndWarm && !($this->pingAndWarmCalled[$instanceId] ?? false)) {
+            // The default deadline is configured by the "clientConfig" option, which uses
+            // `src/V2/resources/bigtable_client_config.json`.
+            // This default deadline should be high enough to absorb cold connection latencies.
+            list($data, $callOptions) = $this->splitOptionalArgs($options);
+            $data['name'] = GapicClient::instanceName($this->projectId, $instanceId);
+            $request = $this->serializer->decodeMessage(new PingAndWarmRequest(), $data);
+            $this->gapicClient->pingAndWarm($request, $callOptions);
+            $this->pingAndWarmCalled[$instanceId] = true;
+        }
+
         return new Table(
             $this->gapicClient,
             $this->serializer,

Bigtable/tests/Unit/BigtableClientTest.php

@@ -19,16 +19,23 @@
 
 use Google\Cloud\Bigtable\BigtableClient;
 use Google\Cloud\Bigtable\Table;
+use Google\Cloud\Bigtable\V2\Client\BigtableClient as BigtableGapicClient;
+use Google\Cloud\Bigtable\V2\PingAndWarmRequest;
+use Google\Cloud\Bigtable\V2\PingAndWarmResponse;
 use Google\Cloud\Core\InsecureCredentialsWrapper;
 use Google\Cloud\Core\Testing\TestHelpers;
 use PHPUnit\Framework\TestCase;
+use Prophecy\Argument;
+use Prophecy\PhpUnit\ProphecyTrait;
 
 /**
  * @group bigtable
  * @group bigtabledata
  */
 class BigtableClientTest extends TestCase
 {
+    use ProphecyTrait;
+
     private $client;
 
     public function setUp(): void
@@ -44,4 +51,61 @@ public function testTable()
 
         $this->assertInstanceOf(Table::class, $table);
     }
+
+    public function testPingAndWarm()
+    {
+        $gapicClient = $this->prophesize(BigtableGapicClient::class);
+        $gapicClient->pingAndWarm(Argument::any())
+            ->shouldNotBeCalled();
+
+        $bigtable = new BigtableClient([
+            'projectId' => 'my-project',
+            'credentials' => new InsecureCredentialsWrapper(),
+        ]);
+        (fn() => $this->gapicClient = $gapicClient->reveal())->call($bigtable);
+
+        // calling "::table" without the option does not pingandwarm
+        $bigtable->table('my-instance', 'my-table');
+
+        // creating the client with the option does not pingandwarm
+        $bigtable = new BigtableClient([
+            'projectId' => 'my-project',
+            'credentials' => new InsecureCredentialsWrapper(),
+            'pingAndWarm' => true, // this would throw an auth error if it was called
+        ]);
+
+        $pingAndWarmResponse = new PingAndWarmResponse();
+        $gapicClient = $this->prophesize(BigtableGapicClient::class);
+        $gapicClient->pingAndWarm(
+            Argument::that(function (PingAndWarmRequest $request) {
+                return $request->getName() === 'projects/my-project/instances/my-instance';
+            }),
+            []
+        )
+            ->shouldBeCalledOnce()
+            ->willReturn($pingAndWarmResponse);
+        $gapicClient->pingAndWarm(
+            Argument::that(function (PingAndWarmRequest $request) {
+                return $request->getName() === 'projects/my-project/instances/my-instance-2';
+            }),
+            []
+        )
+            ->shouldBeCalledOnce()
+            ->willReturn($pingAndWarmResponse);
+
+        // calling "::table" with the option should call pingandwarm
+        $bigtable = new BigtableClient([
+            'projectId' => 'my-project',
+            'credentials' => new InsecureCredentialsWrapper(),
+            'gapicClient' => $gapicClient->reveal(),
+            'pingAndWarm' => true,
+        ]);
+        (fn() => $this->gapicClient = $gapicClient->reveal())->call($bigtable);
+        $bigtable->table('my-instance', 'my-table');
+
+        // "PingAndWarm" will only be called once per instance
+        $bigtable->table('my-instance', 'my-table'); // not called
+        $bigtable->table('my-instance', 'my-table-2'); // still not called
+        $bigtable->table('my-instance-2', 'my-table'); // called
+    }
 }