[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.
  *
@@ -48,7 +45,7 @@ class Iam
     /**
      * @var IamConnectionInterface
      */
-    protected $connection;
+    private $connection;
 
     /**
      * @var string
@@ -61,14 +58,34 @@ class Iam
     private $policy;
 
     /**
-     * @param  IamConnectionInterface $connection
-     * @param  string $resource
+     * @var array
+     */
+    private $args;
+
+    /**
+     * @param IamConnectionInterface $connection
+     * @param string $resource
+     * @param array $options [optional] {
+     *     Configuration Options
+     *
+     *     @type string|null $parent The parent request parameter for the policy.
+     *           If set, policy data will be sent as `request.{$parent}`.
+     *           Otherwise, policy will be sent in request root. **Defaults to**
+     *           `policy`.
+     *     @type array $args Arbitrary data to be sent with the request.
+     * }
      * @access private
      */
-    public function __construct(IamConnectionInterface $connection, $resource)
+    public function __construct(IamConnectionInterface $connection, $resource, array $options = [])
     {
+        $options += [
+            'parent' => 'policy',
+            'args' => []
+        ];
+
         $this->connection = $connection;
         $this->resource = $resource;
+        $this->options = $options;
     }
 
     /**
@@ -109,16 +126,33 @@ 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 \InvalidArgumentException 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,
+        if ($policy instanceof PolicyBuilder) {
+            $policy = $policy->result();
+        }
+
+        if (!is_array($policy)) {
+            throw new \InvalidArgumentException('Given policy data must be an array or an instance of PolicyBuilder.');
+        }
+
+        $request = [];
+        if ($this->options['parent']) {
+            $parent = $this->options['parent'];
+            $request[$parent] = $policy;
+        } else {
+            $request = $policy;
+        }
+
+        return $this->policy = $this->connection->setPolicy([
             'resource' => $this->resource
-        ]);
+        ] + $request + $options + $this->options['args']);
     }
 
     /**
@@ -140,10 +174,12 @@ public function setPolicy(array $policy, array $options = [])
      */
     public function testPermissions(array $permissions, array $options = [])
     {
-        return $this->connection->testPermissions($options + [
+        $res = $this->connection->testPermissions([
             'permissions' => $permissions,
             'resource' => $this->resource
-        ]);
+        ] + $options + $this->options['args']);
+
+        return (isset($res['permissions'])) ? $res['permissions'] : [];
     }
 
     /**
@@ -159,8 +195,8 @@ public function testPermissions(array $permissions, array $options = [])
      */
     public function reload(array $options = [])
     {
-        return $this->policy = $this->connection->getPolicy($options + [
+        return $this->policy = $this->connection->getPolicy([
             'resource' => $this->resource
-        ]);
+        ] + $options + $this->options['args']);
     }
 }

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

@@ -20,9 +20,11 @@
 use Google\Cloud\Core\ArrayTrait;
 use Google\Cloud\Core\Exception\NotFoundException;
 use Google\Cloud\Core\Exception\ServiceException;
+use Google\Cloud\Core\Iam\Iam;
 use Google\Cloud\Core\Upload\ResumableUploader;
 use Google\Cloud\Core\Upload\StreamableUploader;
 use Google\Cloud\Storage\Connection\ConnectionInterface;
+use Google\Cloud\Storage\Connection\IamBucket;
 use GuzzleHttp\Psr7;
 use Psr\Http\Message\StreamInterface;
 
@@ -69,6 +71,11 @@ class Bucket
      */
     private $info;
 
+    /**
+     * @var Iam
+     */
+    private $iam;
+
     /**
      * @param ConnectionInterface $connection Represents a connection to Cloud
      *        Storage.
@@ -779,6 +786,41 @@ public function isWritable($file = null)
     }
 
     /**
+     * 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) {
+            $this->iam = new Iam(
+                new IamBucket($this->connection),
+                $this->identity['bucket'],
+                [
+                    'parent' => null,
+                    'args' => [
+                        'bucket' => $this->identity['bucket']
+                    ]
+                ]
+            );
+        }
+
+        return $this->iam;
+    }
+
+    /*
      * Determines if an object name is required.
      *
      * @param mixed $data

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,65 @@
+<?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)
+    {
+        unset($args['resource']);
+        return $this->connection->setBucketIamPolicy($args);
+    }
+
+    /**
+     * @param  array $args
+     */
+    public function testPermissions(array $args)
+    {
+        unset($args['resource']);
+        return $this->connection->testBucketIamPermissions($args);
+    }
+}

src/Storage/Connection/Rest.php

@@ -310,4 +310,28 @@ private function resolveUploadOptions(array $args)
 
         return $args;
     }
+
+    /**
+     * @param  array $args
+     */
+    public function getBucketIamPolicy(array $args)
+    {
+        return $this->send('buckets', 'getIamPolicy', $args);
+    }
+
+    /**
+     * @param  array $args
+     */
+    public function setBucketIamPolicy(array $args)
+    {
+        return $this->send('buckets', 'setIamPolicy', $args);
+    }
+
+    /**
+     * @param  array $args
+     */
+    public function testBucketIamPermissions(array $args)
+    {
+        return $this->send('buckets', 'testIamPermissions', $args);
+    }
 }