google-cloud-storage 1.29.2 → 1.47.0

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

@@ -191,7 +191,7 @@ module Google
         # @return [Integer]
         #
         def size
-          @gapi.size.to_i if @gapi.size
+          @gapi.size&.to_i
         end
 
         ##
@@ -260,6 +260,9 @@ module Google
         # directive for the file data. If omitted, and the file is accessible
         # to all anonymous users, the default will be `public, max-age=3600`.
         #
+        # To pass generation and/or metageneration preconditions, call this
+        # method within a block passed to {#update}.
+        #
         # @param [String] cache_control The Cache-Control directive.
         #
         def cache_control= cache_control
@@ -281,6 +284,9 @@ module Google
         # Updates the [Content-Disposition](https://tools.ietf.org/html/rfc6266)
         # of the file data.
         #
+        # To pass generation and/or metageneration preconditions, call this
+        # method within a block passed to {#update}.
+        #
         # @param [String] content_disposition The Content-Disposition of the
         #   file.
         #
@@ -305,6 +311,9 @@ module Google
         # ](https://tools.ietf.org/html/rfc7231#section-3.1.2.2) of the file
         # data.
         #
+        # To pass generation and/or metageneration preconditions, call this
+        # method within a block passed to {#update}.
+        #
         # @param [String] content_encoding The Content-Encoding of the file.
         #
         def content_encoding= content_encoding
@@ -326,6 +335,9 @@ module Google
         # Updates the [Content-Language](http://tools.ietf.org/html/bcp47) of
         # the file data.
         #
+        # To pass generation and/or metageneration preconditions, call this
+        # method within a block passed to {#update}.
+        #
         # @param [String] content_language The Content-Language of the file.
         #
         def content_language= content_language
@@ -348,6 +360,9 @@ module Google
         # [Content-Type](https://tools.ietf.org/html/rfc2616#section-14.17) of
         # the file data.
         #
+        # To pass generation and/or metageneration preconditions, call this
+        # method within a block passed to {#update}.
+        #
         # @param [String] content_type The Content-Type of the file.
         #
         def content_type= content_type
@@ -370,6 +385,9 @@ module Google
         # future. If custom_time must be unset, you must either perform a rewrite
         # operation, or upload the data again and create a new file.
         #
+        # To pass generation and/or metageneration preconditions, call this
+        # method within a block passed to {#update}.
+        #
         # @param [DateTime] custom_time A custom time specified by the user
         #   for the file.
         #
@@ -396,6 +414,9 @@ module Google
         # string values that will returned with requests for the file as
         # "x-goog-meta-" response headers.
         #
+        # To pass generation and/or metageneration preconditions, call this
+        # method within a block passed to {#update}.
+        #
         # @param [Hash(String => String)] metadata The user-provided metadata,
         #   in key/value pairs.
         #
@@ -465,6 +486,9 @@ module Google
         # The  default value is the default storage class for the bucket. See
         # {Bucket#storage_class}.
         #
+        # To pass generation and/or metageneration preconditions, call this
+        # method within a block passed to {#update}.
+        #
         # @param [Symbol, String] storage_class Storage class of the file.
         #
         def storage_class= storage_class
@@ -505,6 +529,9 @@ module Google
         # removed, the file's `retention_expires_at` date is not changed. The
         # default value is `false`.
         #
+        # To pass generation and/or metageneration preconditions, call this
+        # method within a block passed to {#update}.
+        #
         # See {#retention_expires_at}.
         #
         # @example
@@ -533,6 +560,9 @@ module Google
         #
         # See {#retention_expires_at}.
         #
+        # To pass generation and/or metageneration preconditions, call this
+        # method within a block passed to {#update}.
+        #
         # @example
         #   require "google/cloud/storage"
         #
@@ -643,6 +673,9 @@ module Google
         #   holds released prior to the effective date of the new policy may
         #   have already been deleted by the user.
         #
+        # To pass generation and/or metageneration preconditions, call this
+        # method within a block passed to {#update}.
+        #
         # @example
         #   require "google/cloud/storage"
         #
@@ -681,6 +714,9 @@ module Google
         # {Bucket#default_event_based_hold?} and
         # {Bucket#default_event_based_hold=}.
         #
+        # To pass generation and/or metageneration preconditions, call this
+        # method within a block passed to {#update}.
+        #
         # @example
         #   require "google/cloud/storage"
         #
@@ -774,6 +810,25 @@ module Google
         # accessible in the block is completely mutable and will be included in the
         # request.
         #
+        # @param [Integer] generation Select a specific revision of the file to
+        #   update. The default is the latest version.
+        # @param [Integer] if_generation_match Makes the operation conditional
+        #   on whether the file's current generation matches the given value.
+        #   Setting to 0 makes the operation succeed only if there are no live
+        #   versions of the file.
+        # @param [Integer] if_generation_not_match Makes the operation conditional
+        #   on whether the file's current generation does not match the given
+        #   value. If no live file exists, the precondition fails. Setting to 0
+        #   makes the operation succeed only if there is a live version of the file.
+        # @param [Integer] if_metageneration_match Makes the operation conditional
+        #   on whether the file's current metageneration matches the given value.
+        # @param [Integer] if_metageneration_not_match Makes the operation
+        #   conditional on whether the file's current metageneration does not
+        #   match the given value.
+        # @param [Boolean] override_unlocked_retention
+        #   Must be true to remove the retention configuration, reduce its unlocked
+        #   retention period, or change its mode from unlocked to locked.
+        #
         # @yield [file] a block yielding a delegate object for updating the file
         #
         # @example
@@ -796,11 +851,36 @@ module Google
         #     f.metadata["score"] = "10"
         #   end
         #
-        def update
+        # @example With a `if_generation_match` precondition:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #
+        #   file.update if_generation_match: 1602263125261858 do |f|
+        #     f.cache_control = "private, max-age=0, no-cache"
+        #   end
+        #
+        def update generation: nil,
+                   if_generation_match: nil,
+                   if_generation_not_match: nil,
+                   if_metageneration_match: nil,
+                   if_metageneration_not_match: nil,
+                   override_unlocked_retention: nil
           updater = Updater.new gapi
           yield updater
           updater.check_for_changed_metadata!
-          update_gapi! updater.updates unless updater.updates.empty?
+          return if updater.updates.empty?
+          update_gapi! updater.updates,
+                       generation: generation,
+                       if_generation_match: if_generation_match,
+                       if_generation_not_match: if_generation_not_match,
+                       if_metageneration_match: if_metageneration_match,
+                       if_metageneration_not_match: if_metageneration_not_match,
+                       override_unlocked_retention: override_unlocked_retention
         end
 
         ##
@@ -1138,6 +1218,27 @@ module Google
         #     access, and allUsers get READER access.
         # @param [Integer] generation Select a specific revision of the file to
         #   rewrite. The default is the latest version.
+        # @param [Integer] if_generation_match Makes the operation conditional
+        #   on whether the destination file's current generation matches the given value.
+        #   Setting to 0 makes the operation succeed only if there are no live
+        #   versions of the file.
+        # @param [Integer] if_generation_not_match Makes the operation conditional
+        #   on whether the destination file's current generation does not match the given
+        #   value. If no live file exists, the precondition fails. Setting to 0
+        #   makes the operation succeed only if there is a live version of the file.
+        # @param [Integer] if_metageneration_match Makes the operation conditional
+        #   on whether the destination file's current metageneration matches the given value.
+        # @param [Integer] if_metageneration_not_match Makes the operation
+        #   conditional on whether the destination file's current metageneration does not
+        #   match the given value.
+        # @param [Integer] if_source_generation_match Makes the operation conditional on
+        #   whether the source object's current generation matches the given value.
+        # @param [Integer] if_source_generation_not_match Makes the operation conditional
+        #   on whether the source object's current generation does not match the given value.
+        # @param [Integer] if_source_metageneration_match Makes the operation conditional
+        #   on whether the source object's current metageneration matches the given value.
+        # @param [Integer] if_source_metageneration_not_match Makes the operation conditional
+        #   on whether the source object's current metageneration does not match the given value.
         # @param [String] encryption_key Optional. The customer-supplied,
         #   AES-256 encryption key used to decrypt the file, if the existing
         #   file is encrypted.
@@ -1259,11 +1360,24 @@ module Google
         #     f.metadata["rewritten_from"] = "#{file.bucket}/#{file.name}"
         #   end
         #
-        def rewrite dest_bucket_or_path, dest_path = nil, acl: nil, generation: nil, encryption_key: nil,
-                    new_encryption_key: nil, new_kms_key: nil, force_copy_metadata: nil
+        def rewrite dest_bucket_or_path,
+                    dest_path = nil,
+                    acl: nil,
+                    generation: nil,
+                    if_generation_match: nil,
+                    if_generation_not_match: nil,
+                    if_metageneration_match: nil,
+                    if_metageneration_not_match: nil,
+                    if_source_generation_match: nil,
+                    if_source_generation_not_match: nil,
+                    if_source_metageneration_match: nil,
+                    if_source_metageneration_not_match: nil,
+                    encryption_key: nil,
+                    new_encryption_key: nil,
+                    new_kms_key: nil,
+                    force_copy_metadata: nil
           ensure_service!
-          dest_bucket, dest_path = fix_rewrite_args dest_bucket_or_path,
-                                                    dest_path
+          dest_bucket, dest_path = fix_rewrite_args dest_bucket_or_path, dest_path
 
           update_gapi = nil
           if block_given?
@@ -1276,9 +1390,21 @@ module Google
             end
           end
 
-          new_gapi = rewrite_gapi bucket, name, update_gapi,
-                                  new_bucket: dest_bucket, new_name: dest_path,
-                                  acl: acl, generation: generation,
+          new_gapi = rewrite_gapi bucket,
+                                  name,
+                                  update_gapi,
+                                  new_bucket: dest_bucket,
+                                  new_name: dest_path,
+                                  acl: acl,
+                                  generation: generation,
+                                  if_generation_match: if_generation_match,
+                                  if_generation_not_match: if_generation_not_match,
+                                  if_metageneration_match: if_metageneration_match,
+                                  if_metageneration_not_match: if_metageneration_not_match,
+                                  if_source_generation_match: if_source_generation_match,
+                                  if_source_generation_not_match: if_source_generation_not_match,
+                                  if_source_metageneration_match: if_source_metageneration_match,
+                                  if_source_metageneration_not_match: if_source_metageneration_not_match,
                                   encryption_key: encryption_key,
                                   new_encryption_key: new_encryption_key,
                                   new_kms_key: new_kms_key,
@@ -1375,6 +1501,20 @@ module Google
         #   {#generation}. The default behavior is to delete the latest version
         #   of the file (regardless of the version to which the file is set,
         #   which is the version returned by {#generation}.)
+        # @param [Integer] if_generation_match Makes the operation conditional
+        #   on whether the file's current generation matches the given value.
+        #   Setting to 0 makes the operation succeed only if there are no live
+        #   versions of the file.
+        # @param [Integer] if_generation_not_match Makes the operation conditional
+        #   on whether the file's current generation does not match the given
+        #   value. If no live file exists, the precondition fails. Setting to 0
+        #   makes the operation succeed only if there is a live version of the file.
+        # @param [Integer] if_metageneration_match Makes the operation conditional
+        #   on whether the file's current metageneration matches the given value.
+        # @param [Integer] if_metageneration_not_match Makes the operation
+        #   conditional on whether the file's current metageneration does not
+        #   match the given value.
+        #
         # @return [Boolean] Returns `true` if the file was deleted.
         #
         # @example
@@ -1407,14 +1547,82 @@ module Google
         #   file = bucket.file "path/to/my-file.ext"
         #   file.delete generation: 123456
         #
-        def delete generation: nil
+        def delete generation: nil,
+                   if_generation_match: nil,
+                   if_generation_not_match: nil,
+                   if_metageneration_match: nil,
+                   if_metageneration_not_match: nil
           generation = self.generation if generation == true
           ensure_service!
-          service.delete_file bucket, name, generation: generation,
-                                            user_project: user_project
+          service.delete_file bucket,
+                              name,
+                              generation: generation,
+                              if_generation_match: if_generation_match,
+                              if_generation_not_match: if_generation_not_match,
+                              if_metageneration_match: if_metageneration_match,
+                              if_metageneration_not_match: if_metageneration_not_match,
+                              user_project: user_project
           true
         end
 
+        # Mode of object level retention configuration.
+        # Valid values are 'Locked' or 'Unlocked'
+        #
+        # @return [String]
+        def retention_mode
+          @gapi.retention&.mode
+        end
+
+        # The earliest time in RFC 3339 UTC "Zulu" format that the object can
+        # be deleted or replaced.
+        #
+        # @return [DateTime]
+        def retention_retain_until_time
+          @gapi.retention&.retain_until_time
+        end
+
+        # A collection of object level retention parameters.
+        # The full list of available options are outlined at the [JSON API docs]
+        # (https://cloud.google.com/storage/docs/json_api/v1/objects/insert#request-body).
+        #
+        # @return [Google::Apis::StorageV1::Object::Retention]
+        def retention
+          @gapi.retention
+        end
+
+        ##
+        # Update method to update retention parameter of an object / file
+        # It accepts params as a Hash of attributes in the following format:
+        #
+        #     { mode: 'Locked|Unlocked', retain_until_time: '2023-12-19T03:22:23+00:00' }
+        #
+        # @param [Hash(String => String)] new_retention_attributes
+        #
+        # @example Update retention parameters for the File / Object
+        #   require "google/cloud/storage"
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #   file = bucket.file "avatars/heidi/400x400.png"
+        #   retention_params = { mode: 'Unlocked', retain_until_time: '2023-12-19T03:22:23+00:00'.to_datetime }
+        #   file.retention = retention_params
+        #
+        # @example Update retention parameters for the File / Object with override enabled
+        #   require "google/cloud/storage"
+        #   storage = Google::Cloud::Storage.new
+        #   bucket = storage.bucket "my-bucket"
+        #   file = bucket.file "avatars/heidi/400x400.png"
+        #   retention_params = { mode: 'Unlocked',
+        #                        retain_until_time: '2023-12-19T03:22:23+00:00'.to_datetime,
+        #                        override_unlocked_retention: true }
+        #   file.retention = retention_params
+        #
+        def retention= new_retention_attributes
+          @gapi.retention ||= Google::Apis::StorageV1::Object::Retention.new
+          @gapi.retention.mode = new_retention_attributes[:mode]
+          @gapi.retention.retain_until_time = new_retention_attributes[:retain_until_time]
+          update_gapi! :retention, override_unlocked_retention: new_retention_attributes[:override_unlocked_retention]
+        end
+
         ##
         # Public URL to access the file. If the file is not public, requests to
         # the URL will return an error. (See {File::Acl#public!} and
@@ -1618,11 +1826,11 @@ module Google
         #     scopes = ["https://www.googleapis.com/auth/iam"]
         #     iam_client.authorization = Google::Auth.get_application_default scopes
         #
-        #     request = {
-        #       "payload": string_to_sign,
-        #     }
+        #     request = Google::Apis::IamcredentialsV1::SignBlobRequest.new(
+        #       payload: string_to_sign
+        #     )
         #     resource = "projects/-/serviceAccounts/#{issuer}"
-        #     response = iam_client.sign_service_account_blob resource, request, {}
+        #     response = iam_client.sign_service_account_blob resource, request
         #     response.signed_blob
         #   end
         #
@@ -1865,7 +2073,14 @@ module Google
           reload! generation: true
         end
 
-        def update_gapi! *attributes
+        def update_gapi! attributes,
+                         generation: nil,
+                         if_generation_match: nil,
+                         if_generation_not_match: nil,
+                         if_metageneration_match: nil,
+                         if_metageneration_not_match: nil,
+                         override_unlocked_retention: nil
+          attributes = Array(attributes)
           attributes.flatten!
           return if attributes.empty?
           update_gapi = self.class.gapi_from_attrs @gapi, attributes
@@ -1873,28 +2088,68 @@ module Google
 
           ensure_service!
 
-          rewrite_attrs = %i[storage_class kms_key_name]
+          rewrite_attrs = [:storage_class, :kms_key_name]
           @gapi = if attributes.any? { |a| rewrite_attrs.include? a }
-                    rewrite_gapi \
-                      bucket, name, update_gapi, user_project: user_project
+                    rewrite_gapi bucket,
+                                 name,
+                                 update_gapi,
+                                 generation: generation,
+                                 if_generation_match: if_generation_match,
+                                 if_generation_not_match: if_generation_not_match,
+                                 if_metageneration_match: if_metageneration_match,
+                                 if_metageneration_not_match: if_metageneration_not_match,
+                                 user_project: user_project
                   else
-                    service.patch_file \
-                      bucket, name, update_gapi, user_project: user_project
+                    service.patch_file bucket,
+                                       name,
+                                       update_gapi,
+                                       generation: generation,
+                                       if_generation_match: if_generation_match,
+                                       if_generation_not_match: if_generation_not_match,
+                                       if_metageneration_match: if_metageneration_match,
+                                       if_metageneration_not_match: if_metageneration_not_match,
+                                       user_project: user_project,
+                                       override_unlocked_retention: override_unlocked_retention
                   end
         end
 
-        def rewrite_gapi bucket, name, updated_gapi,
-                         new_bucket: nil, new_name: nil, acl: nil,
-                         generation: nil, encryption_key: nil,
-                         new_encryption_key: nil, new_kms_key: nil,
+        def rewrite_gapi bucket,
+                         name,
+                         updated_gapi,
+                         new_bucket: nil,
+                         new_name: nil,
+                         acl: nil,
+                         generation: nil,
+                         if_generation_match: nil,
+                         if_generation_not_match: nil,
+                         if_metageneration_match: nil,
+                         if_metageneration_not_match: nil,
+                         if_source_generation_match: nil,
+                         if_source_generation_not_match: nil,
+                         if_source_metageneration_match: nil,
+                         if_source_metageneration_not_match: nil,
+                         encryption_key: nil,
+                         new_encryption_key: nil,
+                         new_kms_key: nil,
                          user_project: nil
           new_bucket ||= bucket
           new_name ||= name
-          options = { acl: File::Acl.predefined_rule_for(acl),
-                      generation: generation, source_key: encryption_key,
-                      destination_key: new_encryption_key,
-                      destination_kms_key: new_kms_key,
-                      user_project: user_project }.delete_if { |_k, v| v.nil? }
+          options = {
+            acl: File::Acl.predefined_rule_for(acl),
+            generation: generation,
+            if_generation_match: if_generation_match,
+            if_generation_not_match: if_generation_not_match,
+            if_metageneration_match: if_metageneration_match,
+            if_metageneration_not_match: if_metageneration_not_match,
+            if_source_generation_match: if_source_generation_match,
+            if_source_generation_not_match: if_source_generation_not_match,
+            if_source_metageneration_match: if_source_metageneration_match,
+            if_source_metageneration_not_match: if_source_metageneration_not_match,
+            source_key: encryption_key,
+            destination_key: new_encryption_key,
+            destination_kms_key: new_kms_key,
+            user_project: user_project
+          }.delete_if { |_k, v| v.nil? }
 
           resp = service.rewrite_file \
             bucket, name, new_bucket, new_name, updated_gapi, **options
@@ -1972,6 +2227,7 @@ module Google
           ##
           # @private Create an Updater object.
           def initialize gapi
+            super()
             @updates = []
             @gapi = gapi
             @metadata ||= @gapi.metadata.to_h.dup

data/lib/google/cloud/storage/hmac_key/list.rb

@@ -131,17 +131,17 @@ module Google
           #     puts key.access_id
           #   end
           #
-          def all request_limit: nil
+          def all request_limit: nil, &block
             request_limit = request_limit.to_i if request_limit
             unless block_given?
               return enum_for :all, request_limit: request_limit
             end
             results = self
             loop do
-              results.each { |r| yield r }
+              results.each(&block)
               if request_limit
                 request_limit -= 1
-                break if request_limit < 0
+                break if request_limit.negative?
               end
               break unless results.next?
               results = results.next

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

@@ -89,7 +89,9 @@ module Google
         #   end
         #
         class Binding
-          attr_reader :role, :members, :condition
+          attr_reader :role
+          attr_reader :members
+          attr_reader :condition
 
           ##
           # Creates a Binding object.
@@ -128,8 +130,8 @@ module Google
             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
+            if condition && !(condition.is_a? Condition)
+              raise ArgumentError, "expected Condition, not #{condition.inspect}"
             end
             @condition = condition
           end

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

@@ -168,10 +168,10 @@ module Google
           #     puts binding.role
           #   end
           #
-          def each
+          def each &block
             return enum_for :each unless block_given?
 
-            @bindings.each { |binding| yield binding }
+            @bindings.each(&block)
           end
 
           ##

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

@@ -70,7 +70,9 @@ module Google
         #   end
         #
         class Condition
-          attr_reader :title, :description, :expression
+          attr_reader :title
+          attr_reader :description
+          attr_reader :expression
 
           ##
           # Creates a Condition object.
@@ -83,7 +85,7 @@ module Google
           #   one attributes, and statements are combined using logic operators,
           #   following CEL language specification. Required.
           #
-          def initialize title:, description: nil, expression:
+          def initialize title:, expression:, description: nil
             @title = String title
             @description = String description
             @expression = String expression

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

@@ -212,8 +212,8 @@ module Google
         def 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
+            roles_dup = p.roles.transform_values do |v|
+              v.dup rescue value
             end
             p.instance_variable_set :@roles, roles_dup
           end

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

@@ -59,7 +59,8 @@ module Google
       #   post.fields["x-goog-signature"] #=> "4893a0e...cd82"
       #
       class PostObject
-        attr_reader :url, :fields
+        attr_reader :url
+        attr_reader :fields
 
         # @private
         def initialize url, fields