[BC Break] Storage IAM

.gitignore

@@ -2,5 +2,5 @@
 build/
 composer.phar
 composer.lock
-docs/json/*
+docs/json/**/*
 vendor/

src/Core/Iam/Iam.php

@@ -23,9 +23,6 @@
  * This class is not meant to be used directly. It should be accessed
  * through other objects which support IAM.
  *
- * Note that examples make use of the PubSub API, and the
- * {@see Google\Cloud\PubSub\Topic} class.
- *
  * Policies can be created using the {@see Google\Cloud\Core\Iam\PolicyBuilder}
  * to help ensure their validity.
  *
@@ -53,16 +50,16 @@ class Iam
     /**
      * @var string
      */
-    private $resource;
+    protected $resource;
 
     /**
      * @var array
      */
-    private $policy;
+    protected $policy;
 
     /**
-     * @param  IamConnectionInterface $connection
-     * @param  string $resource
+     * @param IamConnectionInterface $connection
+     * @param string $resource
      * @access private
      */
     public function __construct(IamConnectionInterface $connection, $resource)
@@ -109,16 +106,23 @@ public function policy(array $options = [])
      * $policy = $iam->setPolicy($oldPolicy);
      * ```
      *
-     * @param  array $policy A new policy array
+     * @param  array|PolicyBuilder $policy The new policy, as an array or an
+     *         instance of {@see Google\Cloud\Core\Iam\PolicyBuilder}.
      * @param  array $options Configuration Options
      * @return array An array of policy data
+     * @throws BadMethodCallException If the given policy is not an array or PolicyBuilder.
      */
-    public function setPolicy(array $policy, array $options = [])
+    public function setPolicy($policy, array $options = [])
     {
-        return $this->policy = $this->connection->setPolicy($options + [
-            'policy' => $policy,
-            'resource' => $this->resource
-        ]);
+        if ($policy instanceof PolicyBuilder) {
+            $policy = $policy->result();
+        }
+
+        if (!is_array($policy)) {
+            throw new \BadMethodCallException('Given policy data must be an array or an instance of PolicyBuilder.');
+        }
+
+        return $this->policy = $this->sendSetPolicyRequest($policy, $options);
     }
 
     /**
@@ -139,14 +143,17 @@ public function setPolicy(array $policy, array $options = [])
      *
      * @param  array $permissions A list of permissions to test
      * @param  array $options Configuration Options
-     * @return array A subset of $permissions, with only those allowed included.
+     * @return array|null A subset of $permissions, with only those allowed
+     *         included, or null.
      */
     public function testPermissions(array $permissions, array $options = [])
     {
-        return $this->connection->testPermissions($options + [
-            'permissions' => $permissions,
-            'resource' => $this->resource
-        ]);
+        $res = $this->sendTestPermissionsRequest($permissions, $options);
+        if (isset($res['permissions'])) {
+            return $res['permissions'];
+        }
+
+        return null;
     }
 
     /**
@@ -162,7 +169,51 @@ public function testPermissions(array $permissions, array $options = [])
      */
     public function reload(array $options = [])
     {
-        return $this->policy = $this->connection->getPolicy($options + [
+        return $this->policy = $this->sendGetPolicyRequest($options);
+    }
+
+    /**
+     * For APIs with non-standard IAM APIs, implementing clients may extend this
+     * class and override this method.
+     *
+     * @param array $policy
+     * @param array $options
+     * @return array
+     */
+    protected function sendSetPolicyRequest(array $policy, array $options)
+    {
+        return $this->connection->setPolicy($options + [
+            'policy' => $policy,
+            'resource' => $this->resource
+        ]);
+    }
+
+    /**
+     * For APIs with non-standard IAM APIs, implementing clients may extend this
+     * class and override this method.
+     *
+     * @param array $options
+     * @return array
+     */
+    protected function sendGetPolicyRequest(array $options)
+    {
+        return $this->connection->getPolicy($options + [
+            'resource' => $this->resource
+        ]);
+    }
+
+    /**
+     * For APIs with non-standard IAM APIs, implementing clients may extend this
+     * class and override this method.
+     *
+     * @param array $permissions
+     * @param array $options
+     * @return array
+     */
+    protected function sendTestPermissionsRequest(array $permissions, array $options)
+    {
+        return $this->connection->testPermissions($options + [
+            'permissions' => $permissions,
             'resource' => $this->resource
         ]);
     }

src/Core/Iam/PolicyBuilder.php

@@ -33,8 +33,6 @@
  */
 class PolicyBuilder
 {
-    const MEMBER_REGEX = '/^((user\:|serviceAccount\:|group\:|domain\:).)|allUsers|allAuthenticatedUsers/';
-
     /**
      * @var array
      */
@@ -117,10 +115,6 @@ public function setBindings(array $bindings = [])
      */
     public function addBinding($role, array $members)
     {
-        foreach ($members as $member) {
-            $this->validateMember($member);
-        }
-
         $this->bindings[] = [
             'role' => $role,
             'members' => $members
@@ -185,18 +179,4 @@ public function result()
             'version' => $this->version
         ]);
     }
-
-    /**
-     * Validate that each member is in the correct format.
-     *
-     * @param  string $member
-     * @throws InvalidArgumentException
-     * @return void
-     */
-    private function validateMember($member)
-    {
-        if (preg_match(self::MEMBER_REGEX, $member) === 0) {
-            throw new InvalidArgumentException('member name is not a valid value.');
-        }
-    }
 }

src/PubSub/Subscription.php

@@ -137,9 +137,6 @@ public function __construct(
                 ? $this->formatName('topic', $topicName, $projectId)
                 : null;
         }
-
-        $iamConnection = new IamSubscription($this->connection);
-        $this->iam = new Iam($iamConnection, $this->name);
     }
 
     /**
@@ -556,6 +553,11 @@ public function modifyPushConfig(array $pushConfig, array $options = [])
      */
     public function iam()
     {
+        if (!$this->iam) {
+            $iamConnection = new IamSubscription($this->connection);
+            $this->iam = new Iam($iamConnection, $this->name);
+        }
+
         return $this->iam;
     }
 

src/PubSub/Topic.php

@@ -105,9 +105,6 @@ public function __construct(
         } else {
             $this->name = $this->formatName('topic', $name, $projectId);
         }
-
-        $iamConnection = new IamTopic($this->connection);
-        $this->iam = new Iam($iamConnection, $this->name);
     }
 
     /**
@@ -441,6 +438,11 @@ function ($subscription) {
      */
     public function iam()
     {
+        if (!$this->iam) {
+            $iamConnection = new IamTopic($this->connection);
+            $this->iam = new Iam($iamConnection, $this->name);
+        }
+
         return $this->iam;
     }
 

src/Storage/Bucket.php

@@ -18,11 +18,12 @@
 namespace Google\Cloud\Storage;
 
 use Google\Cloud\Core\ArrayTrait;
+use Google\Cloud\Core\Exception\NotFoundException;
 use Google\Cloud\Core\Exception\ServiceException;
 use Google\Cloud\Core\Upload\ResumableUploader;
 use Google\Cloud\Core\Upload\StreamableUploader;
-use Google\Cloud\Core\Exception\NotFoundException;
 use Google\Cloud\Storage\Connection\ConnectionInterface;
+use Google\Cloud\Storage\Connection\IamBucket;
 use GuzzleHttp\Psr7;
 use Psr\Http\Message\StreamInterface;
 
@@ -69,6 +70,11 @@ class Bucket
      */
     private $info;
 
+    /**
+     * @var Iam
+     */
+    private $iam;
+
     /**
      * @param ConnectionInterface $connection Represents a connection to Cloud
      *        Storage.
@@ -771,4 +777,36 @@ public function isWritable($file = null)
 
         return true;
     }
+
+    /**
+     * Manage the IAM policy for the current Bucket.
+     *
+     * Example:
+     * ```
+     * $iam = $bucket->iam();
+     * ```
+     *
+     * @codingStandardsIgnoreStart
+     * @see https://cloud.google.com/storage/docs/access-control/iam-with-json-and-xml Storage Access Control Documentation
+     * @see https://cloud.google.com/storage/docs/json_api/v1/buckets/getIamPolicy Get Bucket IAM Policy
+     * @see https://cloud.google.com/storage/docs/json_api/v1/buckets/setIamPolicy Set Bucket IAM Policy
+     * @see https://cloud.google.com/storage/docs/json_api/v1/buckets/testIamPermissions Test Bucket Permissions
+     * @codingStandardsIgnoreEnd
+     *
+     * @return Iam
+     */
+    public function iam()
+    {
+        if (!$this->iam) {
+            $iamConnection = new IamBucket($this->connection);
+            $this->iam = new Iam(
+                $iamConnection,
+                $this->identity['bucket'],
+                ['bucket' => $this->identity['bucket']],
+                'bucket'
+            );
+        }
+
+        return $this->iam;
+    }
 }

src/Storage/Connection/ConnectionInterface.php

@@ -68,6 +68,21 @@ public function listBuckets(array $args = []);
      */
     public function insertBucket(array $args = []);
 
+    /**
+     * @param  array $args
+     */
+    public function getBucketIamPolicy(array $args);
+
+    /**
+     * @param  array $args
+     */
+    public function setBucketIamPolicy(array $args);
+
+    /**
+     * @param  array $args
+     */
+    public function testBucketIamPermissions(array $args);
+
     /**
      * @param array $args
      */

src/Storage/Connection/IamBucket.php

@@ -0,0 +1,63 @@
+<?php
+/**
+ * Copyright 2016 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\Storage\Connection;
+
+use Google\Cloud\Core\Iam\IamConnectionInterface;
+
+/**
+ * IAM Implementation for GCS Buckets
+ */
+class IamBucket implements IamConnectionInterface
+{
+    /**
+     * @var ConnectionInterface
+     */
+    private $connection;
+
+    /**
+     * @param  ConnectionInterface $connection
+     */
+    public function __construct(ConnectionInterface $connection)
+    {
+        $this->connection = $connection;
+    }
+
+    /**
+     * @param  array $args
+     */
+    public function getPolicy(array $args)
+    {
+        return $this->connection->getBucketIamPolicy($args);
+    }
+
+    /**
+     * @param  array $args
+     */
+    public function setPolicy(array $args)
+    {
+        return $this->connection->setBucketIamPolicy($args);
+    }
+
+    /**
+     * @param  array $args
+     */
+    public function testPermissions(array $args)
+    {
+        return $this->connection->testBucketIamPermissions($args);
+    }
+}