google-cloud-storage 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e2f69d45d27d36cc09db5b968a09cbbecf4d8354
-  data.tar.gz: 62b776735c66856f21cfc352541c87c3452f1dc5
+  metadata.gz: e44e7736db1ba058142ad9933e6f70c772271040
+  data.tar.gz: a0c1b589a1b27c357c96764767fcb99ce2c52bf2
 SHA512:
-  metadata.gz: 93933194f259974df44e8961ed44f72d03e666dd15ad65aa082c05546f50438417811619f74e17ba8dc0c2b30a48ec7fa6ec706cd9e93cae454a03aa19965b26
-  data.tar.gz: 825b6a69664ce2c0fab0910234b7b512f430369102db779b627b4083a8b14b9e2e1c50636a0bb74437e07f929f14bebe22539f34a84655325e239aa4bf83661c
+  metadata.gz: fceeaf2cf0932e5d65cb104ca34d72c994d3571c7c39e20c1493d40cb758ac81806f349b77f6833133bf9a131d8b7292e9b61434530f83018c416ecd9c8247a9
+  data.tar.gz: 67d37d87e36555c2f7fb7193d717dedb499447bf014d1b6f34c96b5a4b554ed85c227e3baa4b14ba469346991ddd93df2e700d7f18be49b21a5818f38fb647ff

data/lib/google/cloud/storage/bucket.rb

@@ -16,6 +16,7 @@
 require "google/cloud/storage/bucket/acl"
 require "google/cloud/storage/bucket/list"
 require "google/cloud/storage/bucket/cors"
+require "google/cloud/storage/policy"
 require "google/cloud/storage/post_object"
 require "google/cloud/storage/file"
 require "pathname"
@@ -888,6 +889,140 @@ module Google
           @default_acl ||= Bucket::DefaultAcl.new self
         end
 
+        ##
+        # Gets and updates the [Cloud IAM](https://cloud.google.com/iam/) access
+        # control policy for this bucket.
+        #
+        # @see https://cloud.google.com/iam/docs/managing-policies Managing
+        #   Policies
+        # @see https://cloud.google.com/storage/docs/json_api/v1/buckets/setIamPolicy
+        #   Buckets: setIamPolicy
+        #
+        # @param [Boolean] force Force load the latest policy when `true`.
+        #   Otherwise the policy will be memoized to reduce the number of API
+        #   calls made. The default is `false`.
+        #
+        # @yield [policy] A block for updating the policy. The latest policy
+        #   will be read from the service and passed to the block. After the
+        #   block completes, the modified policy will be written to the service.
+        # @yieldparam [Policy] policy the current Cloud IAM Policy for this
+        #   bucket
+        #
+        # @return [Policy] the current Cloud IAM Policy for this bucket
+        #
+        # @example Policy values are memoized to reduce the number of API calls:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #
+        #   policy = bucket.policy # API call
+        #   policy_2 = bucket.policy # No API call
+        #
+        # @example Use `force` to retrieve the latest policy from the service:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #
+        #   policy = bucket.policy force: true # API call
+        #   policy_2 = bucket.policy force: true # API call
+        #
+        # @example Update the policy by passing a block:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #
+        #   bucket.policy do |p|
+        #     p.add "roles/owner", "user:owner@example.com"
+        #   end # 2 API calls
+        #
+        def policy force: false
+          @policy = nil if force || block_given?
+          @policy ||= begin
+            ensure_service!
+            gapi = service.get_bucket_policy name
+            Policy.from_gapi gapi
+          end
+          return @policy unless block_given?
+          p = @policy.deep_dup
+          yield p
+          self.policy = p
+        end
+
+        ##
+        # Updates the [Cloud IAM](https://cloud.google.com/iam/) access control
+        # policy for this bucket. The policy should be read from {#policy}. See
+        # {Google::Cloud::Storage::Policy} for an explanation of the
+        # policy `etag` property and how to modify policies.
+        #
+        # You can also update the policy by passing a block to {#policy}, which
+        # will call this method internally after the block completes.
+        #
+        # @see https://cloud.google.com/iam/docs/managing-policies Managing
+        #   Policies
+        # @see https://cloud.google.com/storage/docs/json_api/v1/buckets/setIamPolicy
+        #   Buckets: setIamPolicy
+        #
+        # @param [Policy] new_policy a new or modified Cloud IAM Policy for this
+        #   bucket
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #
+        #   policy = bucket.policy # API call
+        #
+        #   policy.add "roles/owner", "user:owner@example.com"
+        #
+        #   bucket.policy = policy # API call
+        #
+        def policy= new_policy
+          ensure_service!
+          gapi = service.set_bucket_policy name, new_policy.to_gapi
+          @policy = Policy.from_gapi gapi
+        end
+
+        ##
+        # Tests the specified permissions against the [Cloud
+        # IAM](https://cloud.google.com/iam/) access control policy.
+        #
+        # @see https://cloud.google.com/iam/docs/managing-policies Managing
+        #   Policies
+        #
+        # @param [String, Array<String>] permissions The set of permissions
+        #   against which to check access. Permissions must be of the format
+        #   `storage.resource.capability`, where resource is one of `buckets` or
+        #   `objects`.
+        #
+        # @return [Array<String>] The permissions held by the caller.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #
+        #   permissions = bucket.test_permissions "storage.buckets.get",
+        #                                         "storage.buckets.delete"
+        #   permissions.include? "storage.buckets.get"    #=> true
+        #   permissions.include? "storage.buckets.delete" #=> false
+        #
+        def test_permissions *permissions
+          permissions = Array(permissions).flatten
+          ensure_service!
+          gapi = service.test_bucket_permissions name, permissions
+          gapi.permissions
+        end
+
         ##
         # Reloads the bucket with current data from the Storage service.
         def reload!

data/lib/google/cloud/storage/policy.rb

@@ -0,0 +1,206 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# 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.
+
+
+require "google/cloud/errors"
+require "google/apis/storage_v1"
+
+module Google
+  module Cloud
+    module Storage
+      ##
+      # # Policy
+      #
+      # Represents a Cloud IAM Policy for the Cloud Storage service.
+      #
+      # A common pattern for updating a resource's metadata, such as its Policy,
+      # is to read the current data from the service, update the data locally,
+      # and then send the modified data for writing. This pattern may result in
+      # a conflict if two or more processes attempt the sequence simultaneously.
+      # IAM solves this problem with the
+      # {Google::Cloud::Storage::Policy#etag} property, which is used to
+      # verify whether the policy has changed since the last request. When you
+      # make a request to with an `etag` value, Cloud IAM compares the `etag`
+      # value in the request with the existing `etag` value associated with the
+      # policy. It writes the policy only if the `etag` values match.
+      #
+      # When you update a policy, first read the policy (and its current `etag`)
+      # from the service, then modify the policy locally, and then write the
+      # modified policy to the service. See
+      # {Google::Cloud::Storage::Bucket#policy} and
+      # {Google::Cloud::Storage::Bucket#policy=}.
+      #
+      # @see https://cloud.google.com/iam/docs/managing-policies Managing
+      #   policies
+      # @see https://cloud.google.com/storage/docs/json_api/v1/buckets/setIamPolicy
+      #   Buckets: setIamPolicy
+      #
+      # @attr [String] etag Used to verify whether the policy has changed since
+      #   the last request. The policy will be written only if the `etag` values
+      #   match.
+      # @attr [Hash{String => Array<String>}] roles The bindings that associate
+      #   roles with an array of members. See [Understanding
+      #   Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+      #   listing of primitive and curated roles. See [Buckets:
+      #   setIamPolicy](https://cloud.google.com/storage/docs/json_api/v1/buckets/setIamPolicy)
+      #   for a listing of values and patterns for members.
+      #
+      # @example
+      #   require "google/cloud/storage"
+      #
+      #   storage = Google::Cloud::Storage.new
+      #
+      #   bucket = storage.bucket "my-todo-app"
+      #
+      #   bucket.policy do |p|
+      #     p.remove "roles/storage.admin", "user:owner@example.com"
+      #     p.add "roles/storage.admin", "user:newowner@example.com"
+      #     p.roles["roles/storage.objectViewer"] = ["allUsers"]
+      #   end
+      #
+      class Policy
+        attr_reader :etag, :roles
+
+        ##
+        # @private Creates a Policy object.
+        def initialize etag, roles
+          @etag = etag
+          @roles = roles
+        end
+
+        ##
+        # Convenience method for adding a member to a binding on this policy.
+        # See [Understanding
+        # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+        # listing of primitive and curated roles. See [Buckets:
+        # setIamPolicy](https://cloud.google.com/storage/docs/json_api/v1/buckets/setIamPolicy)
+        # for a listing of values and patterns for members.
+        #
+        # @param [String] role_name A Cloud IAM role, such as
+        #   `"roles/storage.admin"`.
+        # @param [String] member A Cloud IAM identity, such as
+        #   `"user:owner@example.com"`.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #
+        #   bucket.policy do |p|
+        #     p.add "roles/storage.admin", "user:newowner@example.com"
+        #   end
+        #
+        def add role_name, member
+          role(role_name) << member
+        end
+
+        ##
+        # Convenience method for removing a member from a binding on this
+        # policy. See [Understanding
+        # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+        # listing of primitive and curated roles. See [Buckets:
+        # setIamPolicy](https://cloud.google.com/storage/docs/json_api/v1/buckets/setIamPolicy)
+        # for a listing of values and patterns for members.
+        #
+        # @param [String] role_name A Cloud IAM role, such as
+        #   `"roles/storage.admin"`.
+        # @param [String] member A Cloud IAM identity, such as
+        #   `"user:owner@example.com"`.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #
+        #   bucket.policy do |p|
+        #     p.remove "roles/storage.admin", "user:owner@example.com"
+        #   end
+        #
+        def remove role_name, member
+          role(role_name).delete member
+        end
+
+        ##
+        # Convenience method returning the array of members bound to a role in
+        # this policy, or an empty array if no value is present for the role in
+        # {#roles}. See [Understanding
+        # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+        # listing of primitive and curated roles. See [Buckets:
+        # setIamPolicy](https://cloud.google.com/storage/docs/json_api/v1/buckets/setIamPolicy)
+        # for a listing of values and patterns for members.
+        #
+        # @return [Array<String>] The members strings, or an empty array.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #
+        #   bucket.policy do |p|
+        #     p.role("roles/storage.admin") << "user:owner@example.com"
+        #   end
+        #
+        def role role_name
+          roles[role_name] ||= []
+        end
+
+        ##
+        # Returns a deep copy of the policy.
+        #
+        # @return [Policy]
+        #
+        def deep_dup
+          dup.tap do |p|
+            roles_dup = p.roles.each_with_object({}) do |(k, v), memo|
+              memo[k] = v.dup rescue value
+            end
+            p.instance_variable_set "@roles", roles_dup
+          end
+        end
+
+        ##
+        # @private Convert the Policy to a
+        # Google::Apis::StorageV1::Policy.
+        def to_gapi
+          Google::Apis::StorageV1::Policy.new(
+            etag: etag,
+            bindings: roles.keys.map do |role_name|
+              next if roles[role_name].empty?
+              Google::Apis::StorageV1::Policy::Binding.new(
+                role: role_name,
+                members: roles[role_name]
+              )
+            end
+          )
+        end
+
+        ##
+        # @private New Policy from a
+        # Google::Apis::StorageV1::Policy object.
+        def self.from_gapi gapi
+          roles = gapi.bindings.each_with_object({}) do |binding, memo|
+            memo[binding.role] = binding.members.to_a
+          end
+          new gapi.etag, roles
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/storage/service.rb

@@ -156,6 +156,30 @@ module Google
           end
         end
 
+        ##
+        # Returns Google::Apis::StorageV1::Policy
+        def get_bucket_policy bucket_name
+          # get_bucket_iam_policy(bucket, fields: nil, quota_user: nil,
+          #                               user_ip: nil, options: nil)
+          execute { service.get_bucket_iam_policy bucket_name }
+        end
+
+        ##
+        # Returns Google::Apis::StorageV1::Policy
+        def set_bucket_policy bucket_name, new_policy
+          execute do
+            service.set_bucket_iam_policy bucket_name, new_policy
+          end
+        end
+
+        ##
+        # Returns Google::Apis::StorageV1::TestIamPermissionsResponse
+        def test_bucket_permissions bucket_name, permissions
+          execute do
+            service.test_bucket_iam_permissions bucket_name, permissions
+          end
+        end
+
         ##
         # Retrieves a list of files matching the criteria.
         def list_files bucket_name, options = {}

data/lib/google/cloud/storage/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Storage
-      VERSION = "1.0.0"
+      VERSION = "1.0.1"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-storage
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-04-05 00:00:00.000000000 Z
+date: 2017-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -203,6 +203,7 @@ files:
 - lib/google/cloud/storage/file/list.rb
 - lib/google/cloud/storage/file/signer.rb
 - lib/google/cloud/storage/file/verifier.rb
+- lib/google/cloud/storage/policy.rb
 - lib/google/cloud/storage/post_object.rb
 - lib/google/cloud/storage/project.rb
 - lib/google/cloud/storage/service.rb