google-cloud-storage 1.14.2 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a103ede9c229058fc56896c55d3d9526ee4efa20cb4769afdbc74e8f6fce547
-  data.tar.gz: adfc02f59247159986db4745fd5eed1a5d41659cbb02b18f55dec1ff1e1ed992
+  metadata.gz: e598fdd23bab0f17c14744298b77e1519458f52a7e0b0e9d66c3986ca3da10cc
+  data.tar.gz: 7c1d3ec1f9a93e032f8f40a81eb4adfa725fc90970293f1dce573ded20bc0f49
 SHA512:
-  metadata.gz: d74bef538ff7377a38951093ead007cbfcda6ffae8f0ba7d993a2c8530dac055e5ed397857ccb18df9e0d325ac7102d31eb4a85caeb1c890b6cfd7e27f8ea72e
-  data.tar.gz: f4aa4ae66d1cd255ddf8268735ecaea24a790d03884ba621a5b39f689f7e06c61756772eb29a24a9a16207720d6c0b3377b30957925184d56cbaa66fa7f96c2f
+  metadata.gz: c47223d54f4bbac666083252a49b3a1853afeca995640e8ee54bf8b1f53e36231efb67e3ed57ea06a7da63328df829161b3eade1913bf7c374117f99400108c0
+  data.tar.gz: a68d2d5325c0414c5e0c4d9179ff1321b03f970d72c36544541a33e9458bf4c659e3d2be0c2f1eeb181a76001196f5cb76c132065dbbf64308a6035c53431ff6

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Release History
 
+### 1.15.0 / 2018-10-03
+
+* Add Bucket retention policy
+  * Add retention_policy fields and default_event_based_hold to Bucket.
+  * Add retention_policy and hold fields to File.
+  * Add Bucket#lock_retention_policy!
+  * Add Bucket#metageneration.
+  * Add Bucket#retention_policy_locked?
+  * Add File#(set|release)_temporary_hold!
+  * Add File#(set|release)_event_based_hold!
+
 ### 1.14.2 / 2018-09-20
 
 * Update documentation.

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

@@ -132,6 +132,15 @@ module Google
           @gapi.time_created
         end
 
+        ##
+        # The metadata generation of the bucket.
+        #
+        # @return [Integer] The metageneration.
+        #
+        def metageneration
+          @gapi.metageneration
+        end
+
         ##
         # Returns the current CORS configuration for a static website served
         # from the bucket.
@@ -545,6 +554,209 @@ module Google
           patch_gapi! :encryption
         end
 
+        ##
+        # The period of time (in seconds) that files in the bucket must be
+        # retained, and cannot be deleted, overwritten, or archived.
+        # The value must be between 0 and 100 years (in seconds.)
+        #
+        # See also: {#retention_period=}, {#retention_effective_at}, and
+        # {#retention_policy_locked?}.
+        #
+        # @return [Integer, nil] The retention period defined in seconds, if a
+        #   retention policy exists for the bucket.
+        #
+        def retention_period
+          @gapi.retention_policy && @gapi.retention_policy.retention_period
+        end
+
+        ##
+        # The period of time (in seconds) that files in the bucket must be
+        # retained, and cannot be deleted, overwritten, or archived. Passing a
+        # valid Integer value will add a new retention policy to the bucket
+        # if none exists. Passing `nil` will remove the retention policy from
+        # the bucket if it exists, unless the policy is locked.
+        #
+        # Locked policies can be extended in duration by using this method
+        # to set a higher value. Such an extension is permanent, and it cannot
+        # later be reduced.  The extended duration will apply retroactively to
+        # all files currently in the bucket.
+        #
+        # See also: {#lock_retention_policy!}, {#retention_period},
+        # {#retention_effective_at}, and {#retention_policy_locked?}.
+        #
+        # @param [Integer, nil] new_retention_period The retention period
+        #   defined in seconds. The value must be between 0 and 100 years (in
+        #   seconds), or `nil`.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.retention_period = 2592000 # 30 days in seconds
+        #
+        #   file = bucket.create_file "path/to/local.file.ext"
+        #   file.delete # raises Google::Cloud::PermissionDeniedError
+        #
+        def retention_period= new_retention_period
+          if new_retention_period.nil?
+            @gapi.retention_policy = nil
+          else
+            @gapi.retention_policy ||= \
+              Google::Apis::StorageV1::Bucket::RetentionPolicy.new
+            @gapi.retention_policy.retention_period = new_retention_period
+          end
+
+          patch_gapi! :retention_policy
+        end
+
+        ##
+        # The time from which the retention policy was effective. Whenever a
+        # retention policy is created or extended, GCS updates the effective
+        # date of the policy. The effective date signals the date starting from
+        # which objects were guaranteed to be retained for the full duration of
+        # the policy.
+        #
+        # This field is updated when the retention policy is created or
+        # modified, including extension of a locked policy.
+        #
+        # @return [DateTime, nil] The effective date of the bucket's retention
+        #   policy, if a policy exists.
+        #
+        def retention_effective_at
+          @gapi.retention_policy && @gapi.retention_policy.effective_time
+        end
+
+        ##
+        # Whether the bucket's file retention policy is locked and its retention
+        # period cannot be reduced. See {#retention_period=} and
+        # {#lock_retention_policy!}.
+        #
+        # This value can only be set to `true` by calling
+        # {Bucket#lock_retention_policy!}.
+        #
+        # @return [Boolean] Returns `false` if there is no retention policy or
+        #   if the retention policy is unlocked and the retention period can be
+        #   reduced. Returns `true` if the retention policy is locked and the
+        #   retention period cannot be reduced.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.retention_period = 2592000 # 30 days in seconds
+        #   bucket.lock_retention_policy!
+        #   bucket.retention_policy_locked? # true
+        #
+        #   file = bucket.create_file "path/to/local.file.ext"
+        #   file.delete # raises Google::Cloud::PermissionDeniedError
+        #
+        def retention_policy_locked?
+          return false unless @gapi.retention_policy
+          !@gapi.retention_policy.is_locked.nil? &&
+            @gapi.retention_policy.is_locked
+        end
+
+        ##
+        # Whether the `event_based_hold` field for newly-created files in the
+        # bucket will be initially set to `true`. See
+        # {#default_event_based_hold=}, {File#event_based_hold?} and
+        # {File#set_event_based_hold!}.
+        #
+        # @return [Boolean] Returns `true` if the `event_based_hold` field for
+        #   newly-created files in the bucket will be initially set to `true`,
+        #   otherwise `false`.
+        #
+        def default_event_based_hold?
+          !@gapi.default_event_based_hold.nil? && @gapi.default_event_based_hold
+        end
+
+        ##
+        # Updates the default event-based hold field for the bucket. This field
+        # controls the initial state of the `event_based_hold` field for
+        # newly-created files in the bucket.
+        #
+        # See {File#event_based_hold?} and {File#set_event_based_hold!}.
+        #
+        # @param [Boolean] new_default_event_based_hold The default event-based
+        #   hold field for the bucket.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.update do |b|
+        #     b.retention_period = 2592000 # 30 days in seconds
+        #     b.default_event_based_hold = true
+        #   end
+        #
+        #   file = bucket.create_file "path/to/local.file.ext"
+        #   file.event_based_hold? # true
+        #   file.delete # raises Google::Cloud::PermissionDeniedError
+        #   file.release_event_based_hold!
+        #
+        #   # The end of the retention period is calculated from the time that
+        #   # the event-based hold was released.
+        #   file.retention_expires_at
+        #
+        def default_event_based_hold= new_default_event_based_hold
+          @gapi.default_event_based_hold = new_default_event_based_hold
+          patch_gapi! :default_event_based_hold
+        end
+
+        ##
+        # PERMANENTLY locks the retention policy (see {#retention_period=}) on
+        # the bucket if one exists. The policy is transitioned to a locked state
+        # in which its duration cannot be reduced.
+        #
+        # Locked policies can be extended in duration by setting
+        # {#retention_period=} to a higher value. Such an extension is
+        # permanent, and it cannot later be reduced.  The extended duration will
+        # apply retroactively to all files currently in the bucket.
+        #
+        # This method also [creates a
+        # lien](https://cloud.google.com/resource-manager/reference/rest/v1/liens/create)
+        # on the `resourcemanager.projects.delete` permission for the project
+        # containing the bucket.
+        #
+        # The bucket's metageneration value is required for the lock policy API
+        # call. Attempting to call this method on a bucket that was loaded with
+        # the `skip_lookup: true` option will result in an error.
+        #
+        # @return [Boolean] Returns `true` if the lock operation is successful.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.retention_period = 2592000 # 30 days in seconds
+        #   bucket.lock_retention_policy!
+        #   bucket.retention_policy_locked? # true
+        #
+        #   file = bucket.create_file "path/to/local.file.ext"
+        #   file.delete # raises Google::Cloud::PermissionDeniedError
+        #
+        #   # Locked policies can be extended in duration
+        #   bucket.retention_period = 7776000 # 90 days in seconds
+        #
+        def lock_retention_policy!
+          ensure_service!
+          @gapi = service.lock_bucket_retention_policy \
+            name, metageneration, user_project: user_project
+          true
+        end
+
         ##
         # Updates the bucket with changes made in the given block in a single
         # PATCH request. The following attributes may be set: {#cors},
@@ -909,7 +1121,8 @@ module Google
                         content_disposition: nil, content_encoding: nil,
                         content_language: nil, content_type: nil,
                         crc32c: nil, md5: nil, metadata: nil,
-                        storage_class: nil, encryption_key: nil, kms_key: nil
+                        storage_class: nil, encryption_key: nil, kms_key: nil,
+                        temporary_hold: nil, event_based_hold: nil
           ensure_service!
           options = { acl: File::Acl.predefined_rule_for(acl), md5: md5,
                       cache_control: cache_control, content_type: content_type,
@@ -918,6 +1131,8 @@ module Google
                       content_language: content_language, key: encryption_key,
                       kms_key: kms_key,
                       storage_class: storage_class_for(storage_class),
+                      temporary_hold: temporary_hold,
+                      event_based_hold: event_based_hold,
                       user_project: user_project }
           ensure_io_or_file_exists! file
           path ||= file.path if file.respond_to? :path

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

@@ -447,6 +447,261 @@ module Google
           update_gapi! :storage_class
         end
 
+        ##
+        # Whether there is a temporary hold on the file. A temporary hold will
+        # be enforced on the file as long as this property is `true`, even if
+        # the bucket-level retention policy would normally allow deletion. When
+        # the temporary hold is removed, the normal bucket-level policy rules
+        # once again apply. The default value is `false`.
+        #
+        # @return [Boolean] Returns `true` if there is a temporary hold on the
+        #   file, otherwise `false`.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #   file = bucket.file "path/to/my-file.ext"
+        #
+        #   file.temporary_hold? #=> false
+        #   file.set_temporary_hold!
+        #   file.delete # raises Google::Cloud::PermissionDeniedError
+        #
+        def temporary_hold?
+          !@gapi.temporary_hold.nil? && @gapi.temporary_hold
+        end
+
+        ##
+        # Sets the temporary hold property of the file to `true`. This property
+        # is used to enforce a temporary hold on a file. While it is set to
+        # `true`, the file is protected against deletion and overwrites. Once
+        # removed, the file's `retention_expires_at` date is not changed. The
+        # default value is `false`.
+        #
+        # See {#retention_expires_at}.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #   file = bucket.file "path/to/my-file.ext"
+        #
+        #   file.temporary_hold? #=> false
+        #   file.set_temporary_hold!
+        #   file.delete # raises Google::Cloud::PermissionDeniedError
+        #
+        def set_temporary_hold!
+          @gapi.temporary_hold = true
+          update_gapi! :temporary_hold
+        end
+
+        ##
+        # Sets the temporary hold property of the file to `false`. This property
+        # is used to enforce a temporary hold on a file. While it is set to
+        # `true`, the file is protected against deletion and overwrites. Once
+        # removed, the file's `retention_expires_at` date is not changed. The
+        # default value is `false`.
+        #
+        # See {#retention_expires_at}.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #   file = bucket.file "path/to/my-file.ext"
+        #
+        #   file.temporary_hold? #=> false
+        #   file.set_temporary_hold!
+        #   file.delete # raises Google::Cloud::PermissionDeniedError
+        #
+        #   file.release_temporary_hold!
+        #   file.delete
+        #
+        def release_temporary_hold!
+          @gapi.temporary_hold = false
+          update_gapi! :temporary_hold
+        end
+
+        ##
+        # Whether there is an event-based hold on the file. An event-based
+        # hold will be enforced on the file as long as this property is `true`,
+        # even if the bucket-level retention policy would normally allow
+        # deletion. Removing the event-based hold extends the retention duration
+        # of the file to the current date plus the bucket-level policy duration.
+        # Removing the event-based hold represents that a retention-related
+        # event has occurred, and thus the retention clock ticks from the moment
+        # of the event as opposed to the creation date of the object. The
+        # default value is configured at the bucket level (which defaults to
+        # `false`), and is assigned to newly-created objects.
+        #
+        # See {#set_event_based_hold!}, {#release_event_based_hold!},
+        # {Bucket#default_event_based_hold?} and
+        # {Bucket#default_event_based_hold=}.
+        #
+        # If a bucket's retention policy duration is modified after the
+        # event-based hold flag is unset, the updated retention duration applies
+        # retroactively to objects that previously had event-based holds.  For
+        # example:
+        #
+        # * If the bucket's [unlocked] retention policy is removed, objects with
+        #   event-based holds may be deleted immediately after the hold is
+        #   removed (the duration of a nonexistent policy for the purpose of
+        #   event-based holds is considered to be zero).
+        # * If the bucket's [unlocked] policy is reduced, objects with
+        #   previously released event-based holds will be have their retention
+        #   expiration dates reduced accordingly.
+        # * If the bucket's policy is extended, objects with previously released
+        #   event-based holds will have their retention expiration dates
+        #   extended accordingly.  However, note that objects with event-based
+        #   holds released prior to the effective date of the new policy may
+        #   have already been deleted by the user.
+        #
+        # @return [Boolean] Returns `true` if there is an event-based hold on
+        #   the file, otherwise `false`.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #   bucket.retention_period = 2592000 # 30 days in seconds
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #
+        #   file.event_based_hold? #=> false
+        #   file.set_event_based_hold!
+        #   file.delete # raises Google::Cloud::PermissionDeniedError
+        #   file.release_event_based_hold!
+        #
+        #   # The end of the retention period is calculated from the time that
+        #   # the event-based hold was released.
+        #   file.retention_expires_at
+        #
+        def event_based_hold?
+          !@gapi.event_based_hold.nil? && @gapi.event_based_hold
+        end
+
+        ##
+        # Sets the event-based hold property of the file to `true`. This
+        # property enforces an event-based hold on the file as long as this
+        # property is `true`, even if the bucket-level retention policy would
+        # normally allow deletion. The default value is configured at the
+        # bucket level (which defaults to `false`), and is assigned to
+        # newly-created objects.
+        #
+        # See {#event_based_hold?}, {#release_event_based_hold!},
+        # {Bucket#default_event_based_hold?} and
+        # {Bucket#default_event_based_hold=}.
+        #
+        # If a bucket's retention policy duration is modified after the
+        # event-based hold is removed, the updated retention duration applies
+        # retroactively to objects that previously had event-based holds.  For
+        # example:
+        #
+        # * If the bucket's [unlocked] retention policy is removed, objects with
+        #   event-based holds may be deleted immediately after the hold is
+        #   removed (the duration of a nonexistent policy for the purpose of
+        #   event-based holds is considered to be zero).
+        # * If the bucket's [unlocked] policy is reduced, objects with
+        #   previously released event-based holds will be have their retention
+        #   expiration dates reduced accordingly.
+        # * If the bucket's policy is extended, objects with previously released
+        #   event-based holds will have their retention expiration dates
+        #   extended accordingly.  However, note that objects with event-based
+        #   holds released prior to the effective date of the new policy may
+        #   have already been deleted by the user.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #   bucket.retention_period = 2592000 # 30 days in seconds
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #
+        #   file.event_based_hold? #=> false
+        #   file.set_event_based_hold!
+        #   file.delete # raises Google::Cloud::PermissionDeniedError
+        #   file.release_event_based_hold!
+        #
+        #   # The end of the retention period is calculated from the time that
+        #   # the event-based hold was released.
+        #   file.retention_expires_at
+        #
+        def set_event_based_hold!
+          @gapi.event_based_hold = true
+          update_gapi! :event_based_hold
+        end
+
+        ##
+        # Sets the event-based hold property of the file to `false`. Removing
+        # the event-based hold extends the retention duration of the file to the
+        # current date plus the bucket-level policy duration. Removing the
+        # event-based hold represents that a retention-related event has
+        # occurred, and thus the retention clock ticks from the moment of the
+        # event as opposed to the creation date of the object. The default value
+        # is configured at the bucket level (which defaults to `false`), and is
+        # assigned to newly-created objects.
+        #
+        # See {#event_based_hold?}, {#set_event_based_hold!},
+        # {Bucket#default_event_based_hold?} and
+        # {Bucket#default_event_based_hold=}.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #   bucket.retention_period = 2592000 # 30 days in seconds
+        #
+        #   file = bucket.file "path/to/my-file.ext"
+        #
+        #   file.event_based_hold? #=> false
+        #   file.set_event_based_hold!
+        #   file.delete # raises Google::Cloud::PermissionDeniedError
+        #   file.release_event_based_hold!
+        #
+        #   # The end of the retention period is calculated from the time that
+        #   # the event-based hold was released.
+        #   file.retention_expires_at
+        #
+        def release_event_based_hold!
+          @gapi.event_based_hold = false
+          update_gapi! :event_based_hold
+        end
+
+        ##
+        # The retention expiration time of the file. This field is indirectly
+        # mutable when the retention policy applicable to the object changes.
+        # The date represents the earliest time that the object could be
+        # deleted, assuming no temporary hold is set. (See {#temporary_hold?}.)
+        # It is provided when both of the following are true:
+        #
+        # * There is a retention policy on the bucket.
+        # * The eventBasedHold flag is unset on the object.
+        #
+        # Note that it can be provided even when {#temporary_hold?} is `true`
+        # (so that the user can reason about policy without having to first
+        # unset the temporary hold).
+        #
+        # @return [DateTime, nil] A DateTime representing the earliest time at
+        #   which the object can be deleted, or `nil` if there are no
+        #   restrictions on deleting the object.
+        #
+        def retention_expires_at
+          @gapi.retention_expiration_time
+        end
+
         ##
         # Retrieves a list of versioned files for the current object.
         #
@@ -1041,6 +1296,11 @@ module Google
         ##
         # Permanently deletes the file.
         #
+        # Raises PermissionDeniedError if the object is subject to an active
+        # retention policy or hold. (See {#retention_expires_at},
+        # {Bucket#retention_period}, {#temporary_hold?} and
+        # {#event_based_hold?}.)
+        #
         # @param [Boolean, Integer] generation Specify a version of the file to
         #   delete. When `true`, it will delete the version returned by
         #   {#generation}. The default behavior is to delete the latest version

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

@@ -127,6 +127,17 @@ module Google
           end
         end
 
+        ##
+        # Locks retention policy on a bucket.
+        def lock_bucket_retention_policy bucket_name, metageneration,
+                                         user_project: nil
+          execute do
+            service.lock_bucket_retention_policy \
+              bucket_name, metageneration,
+              user_project: user_project(user_project)
+          end
+        end
+
         ##
         # Retrieves a list of ACLs for the given bucket.
         def list_bucket_acls bucket_name, user_project: nil
@@ -283,13 +294,15 @@ module Google
                         content_encoding: nil, content_language: nil,
                         content_type: nil, crc32c: nil, md5: nil, metadata: nil,
                         storage_class: nil, key: nil, kms_key: nil,
+                        temporary_hold: nil, event_based_hold: nil,
                         user_project: nil
           file_obj = Google::Apis::StorageV1::Object.new(
             { cache_control: cache_control, content_type: content_type,
               content_disposition: content_disposition, md5_hash: md5,
               content_encoding: content_encoding, crc32c: crc32c,
               content_language: content_language, metadata: metadata,
-              storage_class: storage_class }.delete_if { |_k, v| v.nil? }
+              storage_class: storage_class, temporary_hold: temporary_hold,
+              event_based_hold: event_based_hold }.delete_if { |_k, v| v.nil? }
           )
           content_type ||= mime_type_for(path || Pathname(source).to_path)
 

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Storage
-      VERSION = "1.14.2".freeze
+      VERSION = "1.15.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.14.2
+  version: 1.15.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-09-21 00:00:00.000000000 Z
+date: 2018-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core