file.rb in google-cloud-storage-1.47.0

- old
+ new

@@ -823,10 +823,13 @@
         # @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
         #   require "google/cloud/storage"
@@ -863,21 +866,23 @@
         #
         def update generation: nil,
                    if_generation_match: nil,
                    if_generation_not_match: nil,
                    if_metageneration_match: nil,
-                   if_metageneration_not_match: nil
+                   if_metageneration_not_match: nil,
+                   override_unlocked_retention: nil
           updater = Updater.new gapi
           yield updater
           updater.check_for_changed_metadata!
           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
+                       if_metageneration_not_match: if_metageneration_not_match,
+                       override_unlocked_retention: override_unlocked_retention
         end
 
         ##
         # Downloads the file's contents to a local file or an File-like object.
         #
@@ -1558,11 +1563,69 @@
                               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
         # {Bucket::DefaultAcl#public!}) To share a file that is not public see
         # {#signed_url}.
         #
@@ -2013,11 +2076,12 @@
         def update_gapi! attributes,
                          generation: nil,
                          if_generation_match: nil,
                          if_generation_not_match: nil,
                          if_metageneration_match: nil,
-                         if_metageneration_not_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
           return if update_gapi.nil?
@@ -2042,10 +2106,11 @@
                                        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
+                                       user_project: user_project,
+                                       override_unlocked_retention: override_unlocked_retention
                   end
         end
 
         def rewrite_gapi bucket,
                          name,