Add support for etags on bigquery tables and datasets

src/BigQuery/Dataset.php

@@ -19,6 +19,7 @@
 
 use Google\Cloud\BigQuery\Connection\ConnectionInterface;
 use Google\Cloud\Core\ArrayTrait;
+use Google\Cloud\Core\ConcurrencyControlTrait;
 use Google\Cloud\Core\Exception\NotFoundException;
 use Google\Cloud\Core\Iterator\ItemIterator;
 use Google\Cloud\Core\Iterator\PageIterator;
@@ -30,6 +31,7 @@
 class Dataset
 {
     use ArrayTrait;
+    use ConcurrencyControlTrait;
 
     /**
      * @var ConnectionInterface Represents a connection to BigQuery.
@@ -121,6 +123,11 @@ public function delete(array $options = [])
     /**
      * Update the dataset.
      *
+     * Providing an `etag` key as part of `$metadata` will enable simultaneous
+     * update protection. This is useful in preventing override of modifications
+     * made by another user. The resource's current etag can be obtained via a
+     * GET request on the resource.
+     *
      * Example:
      * ```
      * $dataset->update([
@@ -129,6 +136,7 @@ public function delete(array $options = [])
      * ```
      *
      * @see https://cloud.google.com/bigquery/docs/reference/v2/datasets/patch Datasets patch API documentation.
+     * @see https://cloud.google.com/bigquery/docs/api-performance#patch Patch (Partial Update)
      *
      * @param array $metadata The available options for metadata are outlined
      *        at the [Dataset Resource API docs](https://cloud.google.com/bigquery/docs/reference/v2/datasets#resource)
@@ -137,7 +145,9 @@ public function delete(array $options = [])
     public function update(array $metadata, array $options = [])
     {
         $options += $metadata;
-        $this->info = $this->connection->patchDataset($options + $this->identity);
+        $this->info = $this->connection->patchDataset(
+            $this->applyEtagHeader($options + $this->identity)
+        );
 
         return $this->info;
     }

src/BigQuery/Table.php

@@ -19,6 +19,7 @@
 
 use Google\Cloud\BigQuery\Connection\ConnectionInterface;
 use Google\Cloud\Core\ArrayTrait;
+use Google\Cloud\Core\ConcurrencyControlTrait;
 use Google\Cloud\Core\Exception\NotFoundException;
 use Google\Cloud\Core\Iterator\ItemIterator;
 use Google\Cloud\Core\Iterator\PageIterator;
@@ -33,6 +34,7 @@
 class Table
 {
     use ArrayTrait;
+    use ConcurrencyControlTrait;
     use JobConfigurationTrait;
 
     /**
@@ -125,6 +127,11 @@ public function delete(array $options = [])
     /**
      * Update the table.
      *
+     * Providing an `etag` key as part of `$metadata` will enable simultaneous
+     * update protection. This is useful in preventing override of modifications
+     * made by another user. The resource's current etag can be obtained via a
+     * GET request on the resource.
+     *
      * Example:
      * ```
      * $table->update([
@@ -133,6 +140,7 @@ public function delete(array $options = [])
      * ```
      *
      * @see https://cloud.google.com/bigquery/docs/reference/v2/tables/patch Tables patch API documentation.
+     * @see https://cloud.google.com/bigquery/docs/api-performance#patch Patch (Partial Update)
      *
      * @param array $metadata The available options for metadata are outlined
      *        at the [Table Resource API docs](https://cloud.google.com/bigquery/docs/reference/v2/tables#resource)
@@ -141,7 +149,9 @@ public function delete(array $options = [])
     public function update(array $metadata, array $options = [])
     {
         $options += $metadata;
-        $this->info = $this->connection->patchTable($options + $this->identity);
+        $this->info = $this->connection->patchTable(
+            $this->applyEtagHeader($options + $this->identity)
+        );
 
         return $this->info;
     }

src/Core/ConcurrencyControlTrait.php

@@ -0,0 +1,48 @@
+<?php
+/**
+ * Copyright 2017 Google Inc.
+ *
+ * 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.
+ */
+
+namespace Google\Cloud\Core;
+
+/**
+ * Methods to control concurrent updates.
+ */
+trait ConcurrencyControlTrait
+{
+    /**
+     * Apply the If-Match header to requests requiring concurrency control.
+     *
+     * @param array $options
+     * @param string $argName
+     * @return array
+     */
+    private function applyEtagHeader(array $options, $argName = 'etag')
+    {
+        if (isset($options[$argName])) {
+            if (!isset($options['restOptions'])) {
+                $options['restOptions'] = [];
+            }
+
+            if (!isset($options['restOptions']['headers'])) {
+                $options['restOptions']['headers'] = [];
+            }
+
+            $options['restOptions']['headers']['If-Match'] = $options[$argName];
+        }
+
+        return $options;
+    }
+}

tests/system/BigQuery/ManageDatasetsTest.php

@@ -75,6 +75,19 @@ public function testUpdateDataset()
         $this->assertEquals($metadata['friendlyName'], $info['friendlyName']);
     }
 
+    /**
+     * @expectedException Google\Cloud\Core\Exception\FailedPreconditionException
+     */
+    public function testUpdateDatasetConcurrentUpdateFails()
+    {
+        $data = [
+            'friendlyName' => 'foo',
+            'etag' => 'blah'
+        ];
+
+        self::$dataset->update($data);
+    }
+
     public function testReloadsDataset()
     {
         $this->assertEquals('bigquery#dataset', self::$dataset->reload()['kind']);

tests/system/BigQuery/ManageTablesTest.php

@@ -129,6 +129,19 @@ public function testUpdateTable()
         $this->assertEquals($metadata['friendlyName'], $info['friendlyName']);
     }
 
+    /**
+     * @expectedException Google\Cloud\Core\Exception\FailedPreconditionException
+     */
+    public function testUpdateTableConcurrentUpdateFails()
+    {
+        $data = [
+            'friendlyName' => 'foo',
+            'etag' => 'blah'
+        ];
+
+        self::$table->update($data);
+    }
+
     public function testReloadsTable()
     {
         $this->assertEquals('bigquery#table', self::$table->reload()['kind']);

tests/unit/BigQuery/DatasetTest.php

@@ -94,6 +94,22 @@ public function testUpdatesData()
         $this->assertEquals($updateData['friendlyName'], $dataset->info()['friendlyName']);
     }
 
+    public function testUpdatesDataWithEtag()
+    {
+        $updateData = ['friendlyName' => 'wow a name', 'etag' => 'foo'];
+        $this->connection->patchDataset(Argument::that(function ($args) {
+            if ($args['restOptions']['headers']['If-Match'] !== 'foo') return false;
+
+            return true;
+        }))
+            ->willReturn($updateData)
+            ->shouldBeCalledTimes(1);
+        $dataset = $this->getDataset($this->connection, ['friendlyName' => 'another name']);
+        $dataset->update($updateData);
+
+        $this->assertEquals($updateData['friendlyName'], $dataset->info()['friendlyName']);
+    }
+
     public function testGetsTable()
     {
         $dataset = $this->getDataset($this->connection);

tests/unit/BigQuery/TableTest.php

@@ -121,6 +121,22 @@ public function testDelete()
     }
 
     public function testUpdatesData()
+    {
+        $updateData = ['friendlyName' => 'wow a name', 'etag' => 'foo'];
+        $this->connection->patchTable(Argument::that(function ($args) {
+            if ($args['restOptions']['headers']['If-Match'] !== 'foo') return false;
+
+            return true;
+        }))
+            ->willReturn($updateData)
+            ->shouldBeCalledTimes(1);
+        $table = $this->getTable($this->connection, ['friendlyName' => 'another name']);
+        $table->update($updateData);
+
+        $this->assertEquals($updateData['friendlyName'], $table->info()['friendlyName']);
+    }
+
+    public function testUpdatesDataWithEtag()
     {
         $updateData = ['friendlyName' => 'wow a name'];
         $this->connection->patchTable(Argument::any())

tests/unit/Core/ConcurrencyControlTraitTest.php

@@ -0,0 +1,53 @@
+<?php
+/**
+ * Copyright 2017 Google Inc.
+ *
+ * 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.
+ */
+
+namespace Google\Cloud\Tests\Unit\Core;
+
+use Google\Cloud\Core\ConcurrencyControlTrait;
+
+/**
+ * @group core
+ */
+class ConcurrencyControlTraitTest extends \PHPUnit_Framework_TestCase
+{
+    const ETAG = 'foobar';
+
+    private $trait;
+
+    public function setUp()
+    {
+        $this->trait = \Google\Cloud\Dev\impl(ConcurrencyControlTrait::class);
+    }
+
+    public function testApplyEtagHeader()
+    {
+        $input = ['etag' => self::ETAG];
+
+        $res = $this->trait->call('applyEtagHeader', [$input]);
+
+        $this->assertEquals(self::ETAG, $res['restOptions']['headers']['If-Match']);
+    }
+
+    public function testApplyEtagHeaderCustomName()
+    {
+        $input = ['test' => self::ETAG];
+
+        $res = $this->trait->call('applyEtagHeader', [$input, 'test']);
+
+        $this->assertEquals(self::ETAG, $res['restOptions']['headers']['If-Match']);
+    }
+}