google-cloud-storage 1.24.0 → 1.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a70c28bc015c2cde33d22c6af7ad022c4168fd32be38037a18f55e771780b866
-  data.tar.gz: 35c072fa504c5b0d3fd9984765a5049d41d7169755afeadc9e6554d74bb6b3e3
+  metadata.gz: 5a6c22c5d1bf15537e1a8d0b351074e67b32a9f77d70ae4febd9fac791ac1601
+  data.tar.gz: 3378d1c26298d5a6d985ca6b1c2f09f82e00f2303a6953b7b8ee0a077b3fa120
 SHA512:
-  metadata.gz: aa389bb4e5790362bec4d6376e72fd216739d44912c0d3254eb25dde0c83dfbf7ba02ba90ebd94c5d9b3c600bac0cc7c2c62e80128e59388a6426e04e2d21bf7
-  data.tar.gz: 85189ae6d33e7e4e95d42217d7a3aa90e44725c442b0ac912a937b314f27f6b333a3c6b566ffa1d3406f8f8388e2f27665a58174383275ddc5d81d7292c955cc
+  metadata.gz: 6a3409354e221650f8893943755fd72050cd5cfa88960df584d98b9b57ad23ac5342a72857dd13528670ad93931514468e7f8b4dd29f537d4645ff3ca511adf7
+  data.tar.gz: 80cd7709621da535d303d2efd196ef4cddc97cd243d0a4f2400ffcd88cfc5ed113c21ca51ad9e928df1e81dd587b62859f220e90642dedfc761bc86251d1d3cd

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 1.25.0 / 2019-12-12
+
+#### Features
+
+* Add IAM Conditions support to Policy
+
 ### 1.24.0 / 2019-11-12
 
 #### Features
@@ -8,7 +14,7 @@
 
 #### Bug Fixes
 
-* Update #post_object to support special variable ${filename}
+* Update #post_object to support special variable `${filename}`
 
 ### 1.23.0 / 2019-11-05
 

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

@@ -1747,6 +1747,26 @@ module Google
         # @param [Boolean] force [Deprecated] Force the latest policy to be
         #   retrieved from the Storage service when `true`. Deprecated because
         #   the latest policy is now always retrieved. The default is `nil`.
+        # @param [Integer] requested_policy_version The requested syntax schema
+        #   version of the policy. Optional. If `1`, `nil`, or not provided, a
+        #   {Google::Cloud::Storage::PolicyV1} object is returned, which
+        #   provides {Google::Cloud::Storage::PolicyV1#roles} and related
+        #   helpers but does not provide a `bindings` method. If `3` is
+        #   provided, a {Google::Cloud::Storage::PolicyV3} object is returned,
+        #   which provides {Google::Cloud::Storage::PolicyV3#bindings} but does
+        #   not provide a `roles` method or related helpers. A higher version
+        #   indicates that the policy contains role bindings with the newer
+        #   syntax schema that is unsupported by earlier versions.
+        #
+        #   The following requested policy versions are valid:
+        #
+        #   * 1 - The first version of Cloud IAM policy schema. Supports binding one
+        #     role to one or more members. Does not support conditional bindings.
+        #   * 3 - Introduces the condition field in the role binding, which further
+        #     constrains the role binding via context-based and attribute-based rules.
+        #     See [Understanding policies](https://cloud.google.com/iam/docs/policies)
+        #     and [Overview of Cloud IAM Conditions](https://cloud.google.com/iam/docs/conditions-overview)
+        #     for more information.
         #
         # @yield [policy] A block for updating the policy. The latest policy
         #   will be read from the service and passed to the block. After the
@@ -1756,31 +1776,98 @@ module Google
         #
         # @return [Policy] the current Cloud IAM Policy for this bucket
         #
-        # @example
+        # @example Retrieving a Policy that is implicitly version 1:
         #   require "google/cloud/storage"
         #
         #   storage = Google::Cloud::Storage.new
-        #
-        #   bucket = storage.bucket "my-todo-app"
+        #   bucket = storage.bucket "my-bucket"
         #
         #   policy = bucket.policy
+        #   policy.version # 1
+        #   puts policy.roles["roles/storage.objectViewer"]
         #
-        # @example Retrieve the latest policy and update it in a block:
+        # @example Retrieving a version 3 Policy using `requested_policy_version`:
         #   require "google/cloud/storage"
         #
         #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   bucket = storage.bucket "my-todo-app"
+        #   policy = bucket.policy requested_policy_version: 3
+        #   policy.version # 3
+        #   puts policy.bindings.find do |b|
+        #     b[:role] == "roles/storage.objectViewer"
+        #   end
+        #
+        # @example Updating a Policy that is implicitly version 1:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
         #
         #   bucket.policy do |p|
-        #     p.add "roles/owner", "user:owner@example.com"
+        #     p.version # the value is 1
+        #     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
+        #
+        # @example Updating a Policy from version 1 to version 3 by adding a condition:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.uniform_bucket_level_access = true
+        #
+        #   bucket.policy requested_policy_version: 3 do |p|
+        #     p.version # the value is 1
+        #     p.version = 3 # Must be explicitly set to opt-in to support for conditions.
+        #
+        #     expr = "resource.name.startsWith(\"projects/_/buckets/bucket-name/objects/prefix-a-\")"
+        #     p.bindings.insert({
+        #                         role: "roles/storage.admin",
+        #                         members: ["user:owner@example.com"],
+        #                         condition: {
+        #                           title: "my-condition",
+        #                           description: "description of condition",
+        #                           expression: expr
+        #                         }
+        #                       })
         #   end
         #
-        def policy force: nil
+        # @example Updating a version 3 Policy:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.uniform_bucket_level_access? # true
+        #
+        #   bucket.policy requested_policy_version: 3 do |p|
+        #     p.version = 3 # Must be explicitly set to opt-in to support for conditions.
+        #
+        #     expr = "resource.name.startsWith(\"projects/_/buckets/bucket-name/objects/prefix-a-\")"
+        #     p.bindings.insert({
+        #                         role: "roles/storage.admin",
+        #                         members: ["user:owner@example.com"],
+        #                         condition: {
+        #                           title: "my-condition",
+        #                           description: "description of condition",
+        #                           expression: expr
+        #                         }
+        #                       })
+        #   end
+        #
+        def policy force: nil, requested_policy_version: nil
           warn "DEPRECATED: 'force' in Bucket#policy" unless force.nil?
           ensure_service!
-          gapi = service.get_bucket_policy name, user_project: user_project
-          policy = Policy.from_gapi gapi
+          gapi = service.get_bucket_policy name, requested_policy_version: requested_policy_version,
+                                                 user_project: user_project
+          policy = if requested_policy_version.nil? || requested_policy_version == 1
+                     PolicyV1.from_gapi gapi
+                   else
+                     PolicyV3.from_gapi gapi
+                   end
           return policy unless block_given?
           yield policy
           update_policy policy
@@ -1805,24 +1892,70 @@ module Google
         #
         # @return [Policy] The policy returned by the API update operation.
         #
-        # @example
+        # @example Updating a Policy that is implicitly version 1:
         #   require "google/cloud/storage"
         #
         #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
         #
-        #   bucket = storage.bucket "my-todo-app"
+        #   policy = bucket.policy
+        #   policy.version # 1
+        #   policy.remove "roles/storage.admin", "user:owner@example.com"
+        #   policy.add "roles/storage.admin", "user:newowner@example.com"
+        #   policy.roles["roles/storage.objectViewer"] = ["allUsers"]
         #
-        #   policy = bucket.policy # API call
+        #   policy = bucket.update_policy policy
         #
-        #   policy.add "roles/owner", "user:owner@example.com"
+        # @example Updating a Policy from version 1 to version 3 by adding a condition:
+        #   require "google/cloud/storage"
         #
-        #   bucket.update_policy policy # API call
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   policy = bucket.policy requested_policy_version: 3
+        #   policy.version # 1
+        #   policy.version = 3
+        #
+        #   expr = "resource.name.startsWith(\"projects/_/buckets/bucket-name/objects/prefix-a-\")"
+        #   policy.bindings.insert({
+        #                           role: "roles/storage.admin",
+        #                           members: ["user:owner@example.com"],
+        #                           condition: {
+        #                             title: "my-condition",
+        #                             description: "description of condition",
+        #                             expression: expr
+        #                           }
+        #                         })
+        #
+        #   policy = bucket.update_policy policy
+        #
+        # @example Updating a version 3 Policy:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   policy = bucket.policy requested_policy_version: 3
+        #   policy.version # 3 indicates an existing binding with a condition.
+        #
+        #   expr = "resource.name.startsWith(\"projects/_/buckets/bucket-name/objects/prefix-a-\")"
+        #   policy.bindings.insert({
+        #                           role: "roles/storage.admin",
+        #                           members: ["user:owner@example.com"],
+        #                           condition: {
+        #                             title: "my-condition",
+        #                             description: "description of condition",
+        #                             expression: expr
+        #                           }
+        #                         })
+        #
+        #   policy = bucket.update_policy policy
         #
         def update_policy new_policy
           ensure_service!
           gapi = service.set_bucket_policy name, new_policy.to_gapi,
                                            user_project: user_project
-          Policy.from_gapi gapi
+          new_policy.class.from_gapi gapi
         end
         alias policy= update_policy
 
@@ -1845,7 +1978,7 @@ module Google
         #
         #   storage = Google::Cloud::Storage.new
         #
-        #   bucket = storage.bucket "my-todo-app"
+        #   bucket = storage.bucket "my-bucket"
         #
         #   permissions = bucket.test_permissions "storage.buckets.get",
         #                                         "storage.buckets.delete"

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

@@ -15,6 +15,7 @@
 
 require "google/cloud/errors"
 require "google/apis/storage_v1"
+require "google/cloud/storage/policy/bindings"
 
 module Google
   module Cloud
@@ -22,7 +23,9 @@ module Google
       ##
       # # Policy
       #
-      # Represents a Cloud IAM Policy for the Cloud Storage service.
+      # An abstract Cloud IAM Policy for the Cloud Storage service. See concrete
+      # subclasses {Google::Cloud::Storage::PolicyV1} and
+      # {Google::Cloud::Storage::PolicyV3}.
       #
       # 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,
@@ -49,8 +52,45 @@ module Google
       # @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
+      # @attr [Integer] version The syntax schema version of the policy. Each version
+      #   of the policy contains a specific syntax schema that can be used by bindings.
+      #   The newer version may contain role bindings with the newer syntax schema
+      #   that is unsupported by earlier versions. This field is not intended to
+      #   be used for any purposes other than policy syntax schema control.
+      #
+      #   The following policy versions are valid:
+      #
+      #   * 1 -  The first version of Cloud IAM policy schema. Supports binding one
+      #     role to one or more members. Does not support conditional bindings.
+      #   * 3 - Introduces the condition field in the role binding, which further
+      #     constrains the role binding via context-based and attribute-based rules.
+      #     See [Understanding policies](https://cloud.google.com/iam/docs/policies)
+      #     and [Overview of Cloud IAM Conditions](https://cloud.google.com/iam/docs/conditions-overview)
+      #     for more information.
+      #
+      class Policy
+        attr_reader :etag
+        attr_reader :version
+
+        ##
+        # @private Creates a Policy object.
+        def initialize etag, version
+          @etag = etag
+          @version = version
+        end
+      end
+
+      ##
+      # A subclass of {Google::Cloud::Storage::Policy} that supports access to {#roles}
+      # and related helpers. Attempts to call {#bindings} and {#version=} will
+      # raise a runtime error. To update the Policy version and add bindings with a newer
+      # syntax, use {Google::Cloud::Storage::PolicyV3} instead by calling
+      # {Google::Cloud::Storage::Bucket#policy} with `requested_policy_version: 3`. To
+      # obtain instances of this class, call {Google::Cloud::Storage::Bucket#policy}
+      # without the `requested_policy_version` keyword argument.
+      #
+      # @attr [Hash] roles Returns the version 1 bindings (no conditions) as a hash that
+      #   associates roles with arrays 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)
@@ -60,22 +100,22 @@ module Google
       #   require "google/cloud/storage"
       #
       #   storage = Google::Cloud::Storage.new
-      #
-      #   bucket = storage.bucket "my-todo-app"
+      #   bucket = storage.bucket "my-bucket"
       #
       #   bucket.policy do |p|
+      #     p.version # the value is 1
       #     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
+      class PolicyV1 < Policy
+        attr_reader :roles
 
         ##
-        # @private Creates a Policy object.
-        def initialize etag, roles
-          @etag = etag
+        # @private Creates a PolicyV1 object.
+        def initialize etag, version, roles
+          super etag, version
           @roles = roles
         end
 
@@ -97,7 +137,7 @@ module Google
         #
         #   storage = Google::Cloud::Storage.new
         #
-        #   bucket = storage.bucket "my-todo-app"
+        #   bucket = storage.bucket "my-bucket"
         #
         #   bucket.policy do |p|
         #     p.add "roles/storage.admin", "user:newowner@example.com"
@@ -125,7 +165,7 @@ module Google
         #
         #   storage = Google::Cloud::Storage.new
         #
-        #   bucket = storage.bucket "my-todo-app"
+        #   bucket = storage.bucket "my-bucket"
         #
         #   bucket.policy do |p|
         #     p.remove "roles/storage.admin", "user:owner@example.com"
@@ -151,7 +191,7 @@ module Google
         #
         #   storage = Google::Cloud::Storage.new
         #
-        #   bucket = storage.bucket "my-todo-app"
+        #   bucket = storage.bucket "my-bucket"
         #
         #   bucket.policy do |p|
         #     p.role("roles/storage.admin") << "user:owner@example.com"
@@ -170,7 +210,7 @@ module Google
         # @return [Policy]
         #
         def deep_dup
-          warn "DEPRECATED: Storage::Policy#deep_dup"
+          warn "DEPRECATED: Storage::PolicyV1#deep_dup"
           dup.tap do |p|
             roles_dup = p.roles.each_with_object({}) do |(k, v), memo|
               memo[k] = v.dup rescue value
@@ -179,19 +219,32 @@ module Google
           end
         end
 
+        ##
+        # @private Illegal operation in PolicyV1. Use {#roles} instead.
+        #
+        # @raise [RuntimeError] If called on this class.
+        #
+        def bindings
+          raise "Illegal operation unless using PolicyV3. Use #roles instead."
+        end
+
+        ##
+        # @private Illegal operation in PolicyV1. Use {Google::Cloud::Storage::PolicyV3#version=} instead.
+        #
+        # @raise [RuntimeError] If called on this class.
+        #
+        def version=(*)
+          raise "Illegal operation unless using PolicyV3."
+        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].uniq
-              )
-            end
+            version: version,
+            bindings: roles_to_gapi
           )
         end
 
@@ -202,7 +255,207 @@ module Google
           roles = Array(gapi.bindings).each_with_object({}) do |binding, memo|
             memo[binding.role] = binding.members.to_a
           end
-          new gapi.etag, roles
+          new gapi.etag, gapi.version, roles
+        end
+
+        protected
+
+        def roles_to_gapi
+          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].uniq
+            )
+          end
+        end
+      end
+
+      ##
+      # A subclass of {Google::Cloud::Storage::Policy} that supports access to {#bindings}
+      # and {version=}. Attempts to call {#roles} and relate helpers will raise a runtime
+      # error. This class may be used to update the Policy version and add bindings with a newer
+      # syntax. To obtain instances of this class, call {Google::Cloud::Storage::Bucket#policy}
+      # with `requested_policy_version: 3`.
+      #
+      # @attr [Bindings] bindings Returns the Policy's bindings object that associate roles with
+      #   an array of members. Conditions can be configured on the {Binding} object. 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 Updating Policy version 1 to version 3:
+      #   require "google/cloud/storage"
+      #
+      #   storage = Google::Cloud::Storage.new
+      #   bucket = storage.bucket "my-bucket"
+      #
+      #   bucket.uniform_bucket_level_access = true
+      #
+      #   bucket.policy requested_policy_version: 3 do |p|
+      #     p.version # the value is 1
+      #     p.version = 3
+      #
+      #     expr = "resource.name.startsWith(\"projects/_/buckets/bucket-name/objects/prefix-a-\")"
+      #     p.bindings.insert({
+      #                         role: "roles/storage.admin",
+      #                         members: ["user:owner@example.com"],
+      #                         condition: {
+      #                           title: "my-condition",
+      #                           description: "description of condition",
+      #                           expression: expr
+      #                         }
+      #                       })
+      #   end
+      #
+      # @example Using Policy version 3:
+      #   require "google/cloud/storage"
+      #
+      #   storage = Google::Cloud::Storage.new
+      #   bucket = storage.bucket "my-bucket"
+      #
+      #   bucket.uniform_bucket_level_access? # true
+      #
+      #   bucket.policy requested_policy_version: 3 do |p|
+      #     p.version = 3 # Must be explicitly set to opt-in to support for conditions.
+      #
+      #     expr = "resource.name.startsWith(\"projects/_/buckets/bucket-name/objects/prefix-a-\")"
+      #     p.bindings.insert({
+      #                         role: "roles/storage.admin",
+      #                         members: ["user:owner@example.com"],
+      #                         condition: {
+      #                           title: "my-condition",
+      #                           description: "description of condition",
+      #                           expression: expr
+      #                         }
+      #                       })
+      #   end
+      #
+      class PolicyV3 < Policy
+        attr_reader :bindings
+
+        ##
+        # @private Creates a PolicyV3 object.
+        def initialize etag, version, bindings
+          super etag, version
+          @bindings = Bindings.new
+          @bindings.insert(*bindings)
+        end
+
+        ##
+        # Updates the syntax schema version of the policy. Each version of the
+        # policy contains a specific syntax schema that can be used by bindings.
+        # The newer version may contain role bindings with the newer syntax schema
+        # that is unsupported by earlier versions. This field is not intended to
+        # be used for any purposes other than policy syntax schema control.
+        #
+        # The following policy versions are valid:
+        #
+        # * 1 -  The first version of Cloud IAM policy schema. Supports binding one
+        #   role to one or more members. Does not support conditional bindings.
+        # * 3 - Introduces the condition field in the role binding, which further
+        #   constrains the role binding via context-based and attribute-based rules.
+        #   See [Understanding policies](https://cloud.google.com/iam/docs/policies)
+        #   and [Overview of Cloud IAM Conditions](https://cloud.google.com/iam/docs/conditions-overview)
+        #   for more information.
+        #
+        # @param [Integer] new_version The syntax schema version of the policy.
+        #
+        # @see https://cloud.google.com/iam/docs/policies#versions Policy versions
+        #
+        # @example Updating Policy version 1 to version 3:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.uniform_bucket_level_access = true
+        #
+        #   bucket.policy requested_policy_version: 3 do |p|
+        #     p.version # the value is 1
+        #     p.version = 3
+        #
+        #     expr = "resource.name.startsWith(\"projects/_/buckets/bucket-name/objects/prefix-a-\")"
+        #     p.bindings.insert({
+        #                         role: "roles/storage.admin",
+        #                         members: ["user:owner@example.com"],
+        #                         condition: {
+        #                           title: "my-condition",
+        #                           description: "description of condition",
+        #                           expression: expr
+        #                         }
+        #                       })
+        #   end
+        #
+        def version= new_version
+          if new_version < version
+            raise "new_version (#{new_version}) cannot be less than the current version (#{version})."
+          end
+          @version = new_version
+        end
+
+        ##
+        # @private Illegal operation in PolicyV3. Use {#bindings} instead.
+        #
+        # @raise [RuntimeError] If called on this class.
+        #
+        def roles
+          raise "Illegal operation when using PolicyV1. Use Policy#bindings instead."
+        end
+
+        ##
+        # @private Illegal operation in PolicyV3. Use {#bindings} instead.
+        #
+        # @raise [RuntimeError] If called on this class.
+        #
+        def add(*)
+          raise "Illegal operation when using PolicyV1. Use Policy#bindings instead."
+        end
+
+        ##
+        # @private Illegal operation in PolicyV3. Use {#bindings} instead.
+        #
+        # @raise [RuntimeError] If called on this class.
+        #
+        def remove(*)
+          raise "Illegal operation when using PolicyV1. Use Policy#bindings instead."
+        end
+
+        ##
+        # @private Illegal operation in PolicyV3. Use {#bindings} instead.
+        #
+        # @raise [RuntimeError] If called on this class.
+        #
+        def role(*)
+          raise "Illegal operation when using PolicyV1. Use Policy#bindings instead."
+        end
+
+        ##
+        # @private Illegal operation in PolicyV3. Deprecated in PolicyV1.
+        #
+        # @raise [RuntimeError] If called on this class.
+        #
+        def deep_dup
+          raise "Illegal operation when using PolicyV3. Deprecated in PolicyV1."
+        end
+
+        ##
+        # @private Convert the PolicyV3 to a
+        # Google::Apis::StorageV1::Policy.
+        def to_gapi
+          Google::Apis::StorageV1::Policy.new(
+            etag: etag,
+            version: version,
+            bindings: bindings.to_gapi
+          )
+        end
+
+        ##
+        # @private New Policy from a
+        # Google::Apis::StorageV1::Policy object.
+        def self.from_gapi gapi
+          new gapi.etag, gapi.version, Array(gapi.bindings).map(&:to_h)
         end
       end
     end

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

@@ -0,0 +1,243 @@
+# Copyright 2019 Google LLC
+#
+# 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
+#
+#     https://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/storage/policy/condition"
+
+module Google
+  module Cloud
+    module Storage
+      class Policy
+        ##
+        # # Binding
+        #
+        # Value object associating members and an optional condition with a role.
+        #
+        # @see https://cloud.google.com/iam/docs/overview Cloud IAM Overview
+        #
+        # @attr [String] role Role that is assigned to members. For example,
+        #   `roles/viewer`, `roles/editor`, or `roles/owner`. Required.
+        # @attr [Array<String>] members Specifies the identities requesting
+        #   access for a Cloud Platform resource. members can have the
+        #   following values. Required.
+        #
+        #   * `allUsers`: A special identifier that represents anyone who is on
+        #     the internet; with or without a Google account.
+        #   * `allAuthenticatedUsers`: A special identifier that represents
+        #      anyone who is authenticated with a Google account or a service
+        #      account.
+        #   * `user:{emailid}`: An email address that represents a specific
+        #     Google account. For example, `alice@example.com`.
+        #   * `serviceAccount:{emailid}`: An email address that represents a
+        #     service account. For example, `my-other-app@appspot.gserviceaccount.com`.
+        #   * `group:{emailid}`: An email address that represents a Google group.
+        #     For example, `admins@example.com`.
+        #   * `domain:{domain}`: The G Suite domain (primary) that represents
+        #     all the users of that domain. For example, `google.com` or
+        #     `example.com`. Required.
+        #
+        # @attr [Google::Cloud::Storage::Policy::Condition, nil] condition The
+        #   condition that is associated with this binding, or `nil` if there is
+        #   no condition. NOTE: An unsatisfied condition will not allow user
+        #   access via current binding. Different bindings, including their
+        #   conditions, are examined independently.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   policy = bucket.policy requested_policy_version: 3
+        #   policy.bindings.each do |binding|
+        #     puts binding.role
+        #   end
+        #
+        # @example Updating a Policy from version 1 to version 3:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.uniform_bucket_level_access = true
+        #
+        #   bucket.policy requested_policy_version: 3 do |p|
+        #     p.version # the value is 1
+        #     p.version = 3 # Must be explicitly set to opt-in to support for conditions.
+        #
+        #     expr = "resource.name.startsWith(\"projects/_/buckets/bucket-name/objects/prefix-a-\")"
+        #     p.bindings.insert({
+        #                         role: "roles/storage.admin",
+        #                         members: ["user:owner@example.com"],
+        #                         condition: {
+        #                           title: "my-condition",
+        #                           description: "description of condition",
+        #                           expression: expr
+        #                         }
+        #                       })
+        #   end
+        #
+        class Binding
+          attr_reader :role, :members, :condition
+
+          ##
+          # Creates a Binding object.
+          #
+          # @param [String] role Role that is assigned to members. For example,
+          #   `roles/viewer`, `roles/editor`, or `roles/owner`. Required.
+          # @param [Array<String>] members Specifies the identities requesting
+          #   access for a Cloud Platform resource. members can have the
+          #   following values. Required.
+          #
+          #   * `allUsers`: A special identifier that represents anyone who is on
+          #     the internet; with or without a Google account.
+          #   * `allAuthenticatedUsers`: A special identifier that represents
+          #      anyone who is authenticated with a Google account or a service
+          #      account.
+          #   * `user:{emailid}`: An email address that represents a specific
+          #     Google account. For example, `alice@example.com`.
+          #   * `serviceAccount:{emailid}`: An email address that represents a
+          #     service account. For example, `my-other-app@appspot.gserviceaccount.com`.
+          #   * `group:{emailid}`: An email address that represents a Google group.
+          #     For example, `admins@example.com`.
+          #   * `domain:{domain}`: The G Suite domain (primary) that represents
+          #     all the users of that domain. For example, `google.com` or
+          #     `example.com`. Required.
+          #
+          # @param [Google::Cloud::Storage::Policy::Condition] condition The
+          #   condition that is associated with this binding. NOTE: An unsatisfied
+          #   condition will not allow user access via current binding. Different
+          #   bindings, including their conditions, are examined independently.
+          #   Optional.
+          #
+          def initialize role:, members:, condition: nil
+            @role = String role
+
+            @members = Array members
+            raise ArgumentError, "members is empty, must be provided" if @members.empty?
+
+            condition = Condition.new(**condition) if condition.is_a? Hash
+            if condition
+              raise ArgumentError, "expected Condition, not #{condition.inspect}" unless condition.is_a? Condition
+            end
+            @condition = condition
+          end
+
+          ##
+          # Sets the role for the binding.
+          #
+          # @param [String] new_role Role that is assigned to members. For example,
+          #   `roles/viewer`, `roles/editor`, or `roles/owner`. Required.
+          #
+          def role= new_role
+            @role = String new_role
+          end
+
+          ##
+          # Sets the members for the binding.
+          #
+          # @param [Array<String>] new_members Specifies the identities requesting
+          #   access for a Cloud Platform resource. members can have the
+          #   following values. Required.
+          #
+          #   * `allUsers`: A special identifier that represents anyone who is on
+          #     the internet; with or without a Google account.
+          #   * `allAuthenticatedUsers`: A special identifier that represents
+          #      anyone who is authenticated with a Google account or a service
+          #      account.
+          #   * `user:{emailid}`: An email address that represents a specific
+          #     Google account. For example, `alice@example.com`.
+          #   * `serviceAccount:{emailid}`: An email address that represents a
+          #     service account. For example, `my-other-app@appspot.gserviceaccount.com`.
+          #   * `group:{emailid}`: An email address that represents a Google group.
+          #     For example, `admins@example.com`.
+          #   * `domain:{domain}`: The G Suite domain (primary) that represents
+          #     all the users of that domain. For example, `google.com` or
+          #     `example.com`. Required.
+          #
+          def members= new_members
+            new_members = Array new_members
+            raise ArgumentError, "members is empty, must be provided" if new_members.empty?
+            @members = new_members
+          end
+
+          ##
+          # Sets the condition for the binding.
+          #
+          # @param [Google::Cloud::Storage::Policy::Condition] new_condition The
+          #   condition that is associated with this binding. NOTE: An unsatisfied
+          #   condition will not allow user access via current binding. Different
+          #   bindings, including their conditions, are examined independently.
+          #   Optional.
+          # @overload condition=(title:, description: nil, expression:)
+          #   @param [String] title Used to identify the condition. Required.
+          #   @param [String] description Used to document the condition. Optional.
+          #   @param [String] expression Defines an attribute-based logic
+          #     expression using a subset of the Common Expression Language (CEL).
+          #     The condition expression can contain multiple statements, each uses
+          #     one attributes, and statements are combined using logic operators,
+          #     following CEL language specification. Required.
+          #
+          def condition= new_condition
+            new_condition = Condition.new(**new_condition) if new_condition.is_a? Hash
+            if new_condition && !new_condition.is_a?(Condition)
+              raise ArgumentError, "expected Condition, not #{new_condition.inspect}"
+            end
+            @condition = new_condition
+          end
+
+          ##
+          # @private
+          def <=> other
+            return nil unless other.is_a? Binding
+
+            ret = role <=> other.role
+            return ret unless ret.zero?
+            ret = members <=> other.members
+            return ret unless ret.zero?
+            condition&.to_gapi <=> other.condition&.to_gapi
+          end
+
+          ##
+          # @private
+          def eql? other
+            role.eql?(other.role) &&
+              members.eql?(other.members) &&
+              condition&.to_gapi.eql?(other.condition&.to_gapi)
+          end
+
+          ##
+          # @private
+          def hash
+            [
+              @role,
+              @members,
+              @condition&.to_gapi
+            ].hash
+          end
+
+          ##
+          # @private
+          def to_gapi
+            Google::Apis::StorageV1::Policy::Binding.new({
+              role: @role,
+              members: @members,
+              condition: @condition&.to_gapi
+            }.delete_if { |_, v| v.nil? })
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,196 @@
+# Copyright 2019 Google LLC
+#
+# 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
+#
+#     https://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/storage/policy/binding"
+
+module Google
+  module Cloud
+    module Storage
+      class Policy
+        ##
+        # # Bindings
+        #
+        # Enumerable object for managing Cloud IAM bindings associated with
+        # a bucket.
+        #
+        # @see https://cloud.google.com/iam/docs/overview Cloud IAM Overview
+        #
+        # @example Updating a Policy from version 1 to version 3:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.uniform_bucket_level_access = true
+        #
+        #   bucket.policy requested_policy_version: 3 do |p|
+        #     p.version # the value is 1
+        #     p.version = 3 # Must be explicitly set to opt-in to support for conditions.
+        #
+        #     expr = "resource.name.startsWith(\"projects/_/buckets/bucket-name/objects/prefix-a-\")"
+        #     p.bindings.insert({
+        #                         role: "roles/storage.admin",
+        #                         members: ["user:owner@example.com"],
+        #                         condition: {
+        #                           title: "my-condition",
+        #                           description: "description of condition",
+        #                           expression: expr
+        #                         }
+        #                       })
+        #   end
+        #
+        class Bindings
+          include Enumerable
+
+          ##
+          # @private Creates a Bindings object.
+          def initialize
+            @bindings = []
+          end
+
+          ##
+          # Adds a binding or bindings to the collection. The arguments may be
+          # {Google::Cloud::Storage::Policy::Binding} objects or equivalent hash
+          # objects that will be implicitly coerced to binding objects.
+          #
+          # @param [Google::Cloud::Storage::Policy::Binding, Hash] bindings One
+          #   or more bindings to be added to the policy owning the collection.
+          #   The arguments may be {Google::Cloud::Storage::Policy::Binding}
+          #   objects or equivalent hash objects that will be implicitly coerced
+          #   to binding objects.
+          #
+          # @return [Bindings] `self` for chaining.
+          #
+          # @example Updating a Policy from version 1 to version 3:
+          #   require "google/cloud/storage"
+          #
+          #   storage = Google::Cloud::Storage.new
+          #   bucket = storage.bucket "my-bucket"
+          #
+          #   bucket.uniform_bucket_level_access = true
+          #
+          #   bucket.policy requested_policy_version: 3 do |p|
+          #     p.version # the value is 1
+          #     p.version = 3 # Must be explicitly set to opt-in to support for conditions.
+          #
+          #     expr = "resource.name.startsWith(\"projects/_/buckets/bucket-name/objects/prefix-a-\")"
+          #     p.bindings.insert({
+          #                         role: "roles/storage.admin",
+          #                         members: ["user:owner@example.com"],
+          #                         condition: {
+          #                           title: "my-condition",
+          #                           description: "description of condition",
+          #                           expression: expr
+          #                         }
+          #                       })
+          #   end
+          #
+          def insert *bindings
+            bindings = coerce_bindings(*bindings)
+            @bindings += bindings
+            self
+          end
+
+          ##
+          # Deletes the binding or bindings from the collection that are equal to
+          # the arguments. The specification arguments may be
+          # {Google::Cloud::Storage::Policy::Binding} objects or equivalent hash
+          # objects that will be implicitly coerced to binding objects.
+          #
+          # @param [Google::Cloud::Storage::Policy::Binding, Hash] bindings One
+          #   or more specifications for bindings to be removed from the
+          #   collection. The arguments may be
+          #   {Google::Cloud::Storage::Policy::Binding} objects or equivalent
+          #   hash objects that will be implicitly coerced to binding objects.
+          #
+          # @return [Bindings] `self` for chaining.
+          #
+          # @example
+          #   require "google/cloud/storage"
+          #
+          #   storage = Google::Cloud::Storage.new
+          #   bucket = storage.bucket "my-bucket"
+          #
+          #   bucket.policy requested_policy_version: 3 do |p|
+          #     expr = "resource.name.startsWith(\"projects/_/buckets/bucket-name/objects/prefix-a-\")"
+          #     p.bindings.remove({
+          #                         role: "roles/storage.admin",
+          #                         members: ["user:owner@example.com"],
+          #                         condition: {
+          #                           title: "my-condition",
+          #                           description: "description of condition",
+          #                           expression: expr
+          #                         }
+          #                       })
+          #   end
+          #
+          def remove *bindings
+            bindings = coerce_bindings(*bindings)
+            @bindings -= bindings
+            self
+          end
+
+          ##
+          # Calls the block once for each binding in the collection, passing
+          # a {Google::Cloud::Storage::Policy::Binding} object as parameter. A
+          # {Google::Cloud::Storage::Policy::Binding} object is passed even
+          # when the arguments to {#insert} were hash objects.
+          #
+          # If no block is given, an enumerator is returned instead.
+          #
+          # @yield [binding] A binding in this bindings collection.
+          # @yieldparam [Google::Cloud::Storage::Policy::Binding] binding A
+          #   binding object, even when the arguments to {#insert} were hash
+          #   objects.
+          #
+          # @return [Enumerator]
+          #
+          # @example
+          #   require "google/cloud/storage"
+          #
+          #   storage = Google::Cloud::Storage.new
+          #   bucket = storage.bucket "my-bucket"
+          #
+          #   policy = bucket.policy requested_policy_version: 3
+          #   policy.bindings.each do |binding|
+          #     puts binding.role
+          #   end
+          #
+          def each
+            return enum_for :each unless block_given?
+
+            @bindings.each { |binding| yield binding }
+          end
+
+          ##
+          # @private
+          def to_gapi
+            @bindings.map(&:to_gapi)
+          end
+
+          protected
+
+          def coerce_bindings *bindings
+            bindings.map do |binding|
+              binding = Binding.new(**binding) if binding.is_a? Hash
+              raise ArgumentError, "expected Binding, not #{binding.inspect}" unless binding.is_a? Binding
+              binding
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,136 @@
+# Copyright 2019 Google LLC
+#
+# 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
+#
+#     https://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.
+
+
+module Google
+  module Cloud
+    module Storage
+      class Policy
+        ##
+        # # Condition
+        #
+        # Value object accepting an attribute-based logic expression based on a
+        # subset of the Common Expression Language (CEL).
+        #
+        # @see https://cloud.google.com/iam/docs/conditions-overview Cloud IAM
+        #   policies with conditions
+        #
+        # @attr [String] title Used to identify the condition. Required.
+        # @attr [String] description Used to document the condition. Optional.
+        # @attr [String] expression Defines an attribute-based logic
+        #   expression using a subset of the Common Expression Language (CEL).
+        #   The condition expression can contain multiple statements, each uses
+        #   one attributes, and statements are combined using logic operators,
+        #   following CEL language specification. Required.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   policy = bucket.policy requested_policy_version: 3
+        #   policy.bindings.each do |binding|
+        #     puts binding.condition.title if binding.condition
+        #   end
+        #
+        # @example Updating a Policy from version 1 to version 3 by adding a condition:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.uniform_bucket_level_access = true
+        #
+        #   bucket.policy requested_policy_version: 3 do |p|
+        #     p.version # the value is 1
+        #     p.version = 3 # Must be explicitly set to opt-in to support for conditions.
+        #
+        #     expr = "resource.name.startsWith(\"projects/_/buckets/bucket-name/objects/prefix-a-\")"
+        #     p.bindings.insert({
+        #                         role: "roles/storage.admin",
+        #                         members: ["user:owner@example.com"],
+        #                         condition: {
+        #                           title: "my-condition",
+        #                           description: "description of condition",
+        #                           expression: expr
+        #                         }
+        #                       })
+        #   end
+        #
+        class Condition
+          attr_reader :title, :description, :expression
+
+          ##
+          # Creates a Condition object.
+          #
+          # @param [String] title Used to identify the condition. Required.
+          # @param [String] description Used to document the condition. Optional.
+          # @param [String] expression Defines an attribute-based logic
+          #   expression using a subset of the Common Expression Language (CEL).
+          #   The condition expression can contain multiple statements, each uses
+          #   one attributes, and statements are combined using logic operators,
+          #   following CEL language specification. Required.
+          #
+          def initialize title:, description: nil, expression:
+            @title = String title
+            @description = String description
+            @expression = String expression
+          end
+
+          ##
+          # The title used to identify the condition. Required.
+          #
+          # @param [String] new_title The new title.
+          #
+          def title= new_title
+            @title = String new_title
+          end
+
+          ##
+          # The description to document the condition. Optional.
+          #
+          # @param [String] new_description The new description.
+          #
+          def description= new_description
+            @description = String new_description
+          end
+
+          ##
+          # An attribute-based logic expression using a subset of the Common
+          # Expression Language (CEL). The condition expression can contain
+          # multiple statements, each uses one attributes, and statements are
+          # combined using logic operators, following CEL language
+          # specification. Required.
+          #
+          # @see https://cloud.google.com/iam/docs/conditions-overview CEL for conditions
+          #
+          # @param [String] new_expression The new expression.
+          #
+          def expression= new_expression
+            @expression = String new_expression
+          end
+
+          def to_gapi
+            {
+              title: @title,
+              description: @description,
+              expression: @expression
+            }.delete_if { |_, v| v.nil? }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -202,12 +202,12 @@ module Google
 
         ##
         # Returns Google::Apis::StorageV1::Policy
-        def get_bucket_policy bucket_name, user_project: nil
+        def get_bucket_policy bucket_name, requested_policy_version: nil, user_project: nil
           # get_bucket_iam_policy(bucket, fields: nil, quota_user: nil,
           #                               user_ip: nil, options: nil)
           execute do
-            service.get_bucket_iam_policy \
-              bucket_name, user_project: user_project(user_project)
+            service.get_bucket_iam_policy bucket_name, options_requested_policy_version: requested_policy_version,
+                                                       user_project: user_project(user_project)
           end
         end
 

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Storage
-      VERSION = "1.24.0".freeze
+      VERSION = "1.25.0".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-storage
 version: !ruby/object:Gem::Version
-  version: 1.24.0
+  version: 1.25.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-12 00:00:00.000000000 Z
+date: 2019-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -272,6 +272,9 @@ files:
 - lib/google/cloud/storage/hmac_key/list.rb
 - lib/google/cloud/storage/notification.rb
 - lib/google/cloud/storage/policy.rb
+- lib/google/cloud/storage/policy/binding.rb
+- lib/google/cloud/storage/policy/bindings.rb
+- lib/google/cloud/storage/policy/condition.rb
 - lib/google/cloud/storage/post_object.rb
 - lib/google/cloud/storage/project.rb
 - lib/google/cloud/storage/service.rb