google-cloud-storage 1.35.0 → 1.54.0

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

@@ -109,6 +109,24 @@ module Google
           @gapi.id
         end
 
+        ##
+        # The autoclass configuration of the bucket
+        #
+        # @return [Google::Apis::StorageV1::Bucket::Autoclass]
+        #
+        def autoclass
+          @gapi.autoclass
+        end
+
+        ##
+        # The object retention configuration of the bucket
+        #
+        # @return [Google::Apis::StorageV1::Bucket::ObjectRetention]
+        #
+        def object_retention
+          @gapi.object_retention
+        end
+
         ##
         # The name of the bucket.
         #
@@ -279,7 +297,7 @@ module Google
         #
         # @return [String]
         #
-        # @see https://cloud.google.com/storage/docs/concepts-techniques
+        # @see https://cloud.google.com/storage/docs/locations
         #
         def location
           @gapi.location
@@ -301,6 +319,20 @@ module Google
           @gapi.location_type
         end
 
+        ##
+        # Returns the list of regional locations for custom dual-region buckets.
+        #
+        # @return [String, nil] Returns nil if the property has not been set before creation,
+        # if the bucket's resource has not been loaded from the server,
+        # or if the bucket is not a dual-regions bucket.
+
+        # @see https://cloud.google.com/storage/docs/json_api/v1/buckets and
+        # https://cloud.google.com/storage/docs/locations
+        #
+        def data_locations
+          @gapi.custom_placement_config&.data_locations
+        end
+
         ##
         # The destination bucket name for the bucket's logs.
         #
@@ -393,6 +425,77 @@ module Google
           patch_gapi! :storage_class
         end
 
+        ##
+        # Whether Autoclass is enabled for the bucket.
+        #
+        # @return [Boolean]
+        #
+        def autoclass_enabled
+          @gapi.autoclass&.enabled?
+        end
+
+        ##
+        # Toggle time of the autoclass
+        #
+        # @return [DateTime]
+        #
+        def autoclass_toggle_time
+          @gapi.autoclass&.toggle_time
+        end
+
+        ##
+        # Terminal Storage class of the autoclass
+        #
+        # @return [String]
+        #
+        def autoclass_terminal_storage_class
+          @gapi.autoclass&.terminal_storage_class
+        end
+
+        ##
+        # Update time at which the autoclass terminal storage class was last modified
+        #
+        # @return [DateTime]
+        #
+        def autoclass_terminal_storage_class_update_time
+          @gapi.autoclass&.terminal_storage_class_update_time
+        end
+
+        ##
+        # Updates bucket's autoclass configuration. This defines the default class for objects in the
+        # bucket and down/up-grades the storage class of objects based on the access patterns.
+        # Accepted values are `:false`, and `:true`.
+        #
+        # For more information, see [Storage
+        # Classes](https://cloud.google.com/storage/docs/using-autoclass).
+        #
+        # @param [Boolean] toggle for autoclass configuration of the bucket.
+        #
+        def autoclass_enabled= toggle
+          @gapi.autoclass ||= API::Bucket::Autoclass.new
+          @gapi.autoclass.enabled = toggle
+          patch_gapi! :autoclass
+        end
+
+        ##
+        # Update method to update all attributes of autoclass of a bucket
+        # It accepts params as a Hash of attributes in the following format:
+        #
+        #     { enabled: true, terminal_storage_class: "ARCHIVE" }
+        #
+        # terminal_storage_class field is optional. It defaults to `NEARLINE`.
+        # Valid terminal_storage_class values are `NEARLINE` and `ARCHIVE`.
+        #
+        # @param [Hash(String => String)] autoclass_attributes
+        #
+        def update_autoclass autoclass_attributes
+          @gapi.autoclass ||= API::Bucket::Autoclass.new
+          autoclass_attributes.each do |k, v|
+            @gapi.autoclass.send "#{k}=", v
+          end
+          patch_gapi! :autoclass
+        end
+
         ##
         # Whether [Object
         # Versioning](https://cloud.google.com/storage/docs/object-versioning)
@@ -1035,6 +1138,177 @@ module Google
 
         alias public_access_prevention_unspecified? public_access_prevention_inherited?
 
+        ##
+        # Recovery Point Objective (RPO) is another attribute of a bucket, it measures how long it takes for a set of
+        # updates to be asynchronously copied to the other region.
+        # Currently, `DEFAULT` and `ASYNC_TURBO` are supported. When set to `ASYNC_TURBO`, Turbo Replication is enabled
+        # for a bucket. `DEFAULT` is used to reset rpo on an existing bucket with rpo set to `ASYNC_TURBO`.
+        # This value can be modified by calling {#rpo=}.
+        #
+        # @return [String, nil] Currently, `DEFAULT` and `ASYNC_TURBO` are supported. Returns `nil` if the bucket has
+        #    no RPO.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.rpo = :DEFAULT
+        #   bucket.rpo #=> "DEFAULT"
+        #
+        def rpo
+          @gapi.rpo
+        end
+
+        ##
+        # Sets the value for Recovery Point Objective (RPO) in the bucket. This value can be queried by calling {#rpo}.
+        #
+        # @param [Symbol, String] new_rpo The bucket's new Recovery Point Objective metadata.
+        #   Currently, `DEFAULT` and `ASYNC_TURBO` are supported. When set to `ASYNC_TURBO`, Turbo Replication
+        #   is enabled for a bucket.
+        #
+        # @example Set RPO to DEFAULT:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.rpo = :DEFAULT
+        #   bucket.rpo #=> "DEFAULT"
+        #
+        # @example Set RPO to ASYNC_TURBO:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.rpo = :ASYNC_TURBO
+        #   bucket.rpo #=> "ASYNC_TURBO"
+        #
+        def rpo= new_rpo
+          @gapi.rpo = new_rpo&.to_s
+          patch_gapi! :rpo
+        end
+
+        ##
+        # The bucket's soft delete policy. If this policy is set, any deleted
+        # objects will be soft-deleted according to the time specified in the
+        # policy.
+        # This value can be modified by calling {#soft_delete_policy=}.
+        #
+        # @return [Google::Apis::StorageV1::Bucket::SoftDeletePolicy] The default retention policy is for 7
+        # days.
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.soft_delete_policy
+        #
+        def soft_delete_policy
+          @gapi.soft_delete_policy
+        end
+
+        ##
+        # Sets the value for Soft Delete Policy in the bucket. This value can
+        # be queried by calling {#soft_delete_policy}.
+        #
+        # @param [Google::Apis::StorageV1::Bucket::SoftDeletePolicy,
+        #         Hash(String => String)] new_soft_delete_policy The bucket's
+        #         new Soft Delete Policy.
+        #
+        # @example Set Soft Delete Policy to 10 days using SoftDeletePolicy class:
+        #   require "google/cloud/storage"
+        #   require "date"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   soft_delete_policy = Google::Apis::StorageV1::Bucket::SoftDeletePolicy.new
+        #   soft_delete_policy.retention_duration_seconds = 10*24*60*60
+        #
+        #   bucket.soft_delete_policy = soft_delete_policy
+        #
+        # @example Set Soft Delete Policy to 5 days using Hash:
+        #   require "google/cloud/storage"
+        #   require "date"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   soft_delete_policy = { retention_duration_seconds: 432000 }
+        #   bucket.soft_delete_policy = soft_delete_policy
+        #
+        def soft_delete_policy= new_soft_delete_policy
+          @gapi.soft_delete_policy = new_soft_delete_policy || {}
+          patch_gapi! :soft_delete_policy
+        end
+
+        ##
+        # The bucket's hierarchical namespace (Folders) configuration.
+        # This value can be modified by calling {#hierarchical_namespace=}.
+        #
+        # @return [Google::Apis::StorageV1::Bucket::HierarchicalNamespace]
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.hierarchical_namespace
+        #
+        def hierarchical_namespace
+          @gapi.hierarchical_namespace
+        end
+
+        ##
+        # Sets the value of Hierarchical Namespace (Folders) for the bucket.
+        # This can only be enabled at bucket create time. If this is enabled,
+        # Uniform Bucket-Level Access must also be enabled.
+        # This value can be queried by calling {#hierarchical_namespace}.
+        #
+        # @param [Google::Apis::StorageV1::Bucket::HierarchicalNamespace,
+        #         Hash(String => String)] new_hierarchical_namespace The
+        #         bucket's new Hierarchical Namespace Configuration.
+        #
+        # @example Enabled Hierarchical Namespace using HierarchicalNamespace class:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   hierarchical_namespace = Google::Apis::StorageV1::Bucket::HierarchicalNamespace.new
+        #   hierarchical_namespace.enabled = true
+        #
+        #   bucket.hierarchical_namespace = hierarchical_namespace
+        #
+        # @example Disable Hierarchical Namespace using Hash:
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   hierarchical_namespace = { enabled: false }
+        #   bucket.hierarchical_namespace = hierarchical_namespace
+        #
+        def hierarchical_namespace= new_hierarchical_namespace
+          @gapi.hierarchical_namespace = new_hierarchical_namespace || {}
+          patch_gapi! :hierarchical_namespace
+        end
+
         ##
         # Updates the bucket with changes made in the given block in a single
         # PATCH request. The following attributes may be set: {#cors},
@@ -1100,9 +1374,9 @@ module Google
           updater.check_for_mutable_cors!
           updater.check_for_mutable_lifecycle!
           return if updater.updates.empty?
-          patch_gapi! updater.updates,
-                      if_metageneration_match: if_metageneration_match,
-                      if_metageneration_not_match: if_metageneration_not_match
+          update_gapi! updater.updates,
+                       if_metageneration_match: if_metageneration_match,
+                       if_metageneration_not_match: if_metageneration_not_match
         end
 
         ##
@@ -1149,6 +1423,9 @@ module Google
         #   `prefixes` are omitted.
         # @param [String] token A previously-returned page token representing
         #   part of the larger set of results to view.
+        # @param [String] match_glob A glob pattern used to filter results returned in items (e.g. `foo*bar`).
+        #    The string value must be UTF-8 encoded. See:
+        #    https://cloud.google.com/storage/docs/json_api/v1/objects/list#list-object-glob
         # @param [Integer] max Maximum number of items plus prefixes to return.
         #   As duplicate prefixes are omitted, fewer total results may be
         #   returned than requested. The default value of this parameter is
@@ -1157,6 +1434,11 @@ module Google
         #   as distinct results. The default is `false`. For more information,
         #   see [Object Versioning
         #   ](https://cloud.google.com/storage/docs/object-versioning).
+        # @param [Boolean] include_folders_as_prefixes If `true`, will also include
+        #   folders and managed folders, besides objects, in the returned prefixes.
+        #   Only applicable if delimiter is set to '/'.
+        # @param [Boolean] soft_deleted If true, only soft-deleted object
+        #   versions will be listed. The default is false.
         #
         # @return [Array<Google::Cloud::Storage::File>] (See
         #   {Google::Cloud::Storage::File::List})
@@ -1184,14 +1466,22 @@ module Google
         #   end
         #
         def files prefix: nil, delimiter: nil, token: nil, max: nil,
-                  versions: nil
+                  versions: nil, match_glob: nil, include_folders_as_prefixes: nil,
+                  soft_deleted: nil
           ensure_service!
           gapi = service.list_files name, prefix: prefix, delimiter: delimiter,
                                           token: token, max: max,
                                           versions: versions,
-                                          user_project: user_project
+                                          user_project: user_project,
+                                          match_glob: match_glob,
+                                          include_folders_as_prefixes: include_folders_as_prefixes,
+                                          soft_deleted: soft_deleted
           File::List.from_gapi gapi, service, name, prefix, delimiter, max,
-                               versions, user_project: user_project
+                               versions,
+                               user_project: user_project,
+                               match_glob: match_glob,
+                               include_folders_as_prefixes: include_folders_as_prefixes,
+                               soft_deleted: soft_deleted
         end
         alias find_files files
 
@@ -1227,6 +1517,8 @@ module Google
         # @param [String] encryption_key Optional. The customer-supplied,
         #   AES-256 encryption key used to encrypt the file, if one was provided
         #   to {#create_file}. (Not used if `skip_lookup` is also set.)
+        # @param [Boolean] soft_deleted Optional. If true, only soft-deleted
+        #   object versions will be listed. The default is false.
         #
         # @return [Google::Cloud::Storage::File, nil] Returns nil if file does
         #   not exist
@@ -1248,7 +1540,8 @@ module Google
                  if_metageneration_match: nil,
                  if_metageneration_not_match: nil,
                  skip_lookup: nil,
-                 encryption_key: nil
+                 encryption_key: nil,
+                 soft_deleted: nil
           ensure_service!
           if skip_lookup
             return File.new_lazy name, path, service,
@@ -1261,7 +1554,8 @@ module Google
                                               if_metageneration_match: if_metageneration_match,
                                               if_metageneration_not_match: if_metageneration_not_match,
                                               key: encryption_key,
-                                              user_project: user_project
+                                              user_project: user_project,
+                                              soft_deleted: soft_deleted
           File.from_gapi gapi, service, user_project: user_project
         rescue Google::Cloud::NotFoundError
           nil
@@ -1542,6 +1836,77 @@ module Google
         alias upload_file create_file
         alias new_file create_file
 
+        ##
+        # Restores a soft-deleted object.
+        #
+        # @param [String] file_path
+        #   Name of the file.
+        # @param [Fixnum] generation
+        #   Selects a specific revision of this object.
+        # @param [Boolean] copy_source_acl
+        #   If true, copies the source file's ACL; otherwise, uses the
+        #   bucket's default file ACL. The default is false.
+        # @param [Fixnum] if_generation_match
+        #   Makes the operation conditional on whether the file's one live
+        #   generation matches the given value. Setting to 0 makes the
+        #   operation succeed only if there are no live versions of the file.
+        # @param [Fixnum] if_generation_not_match
+        #   Makes the operation conditional on whether none of the file's live
+        #   generations 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 [Fixnum] if_metageneration_match
+        #   Makes the operation conditional on whether the file's one live
+        #   metageneration matches the given value.
+        # @param [Fixnum] if_metageneration_not_match
+        #   Makes the operation conditional on whether none of the object's
+        #   live metagenerations match the given value.
+        # @param [String] projection
+        #   Set of properties to return. Defaults to full.
+        # @param [String] user_project
+        #   The project to be billed for this request. Required for Requester
+        #   Pays buckets.
+        # @param [String] fields
+        #   Selector specifying which fields to include in a partial response.
+        #
+        # @return [Google::Cloud::Storage::File]
+        #
+        # @example
+        #   require "google/cloud/storage"
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-bucket"
+        #
+        #   bucket.restore_file "path/of/file", <generation-of-the-file>
+        #
+        def restore_file file_path,
+                         generation,
+                         copy_source_acl: nil,
+                         if_generation_match: nil,
+                         if_generation_not_match: nil,
+                         if_metageneration_match: nil,
+                         if_metageneration_not_match: nil,
+                         projection: nil,
+                         user_project: nil,
+                         fields: nil,
+                         options: {}
+          ensure_service!
+          gapi = service.restore_file name,
+                                      file_path,
+                                      generation,
+                                      copy_source_acl: File::Acl.predefined_rule_for(copy_source_acl),
+                                      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,
+                                      projection: projection,
+                                      user_project: user_project,
+                                      fields: fields,
+                                      options: options
+          File.from_gapi gapi, service, user_project: user_project
+        end
+
         ##
         # Concatenates a list of existing files in the bucket into a new file in
         # the bucket. There is a limit (currently 32) to the number of files
@@ -2822,9 +3187,9 @@ module Google
           attributes.flatten!
           return if attributes.empty?
           ensure_service!
-          patch_args = Hash[attributes.map do |attr|
+          patch_args = attributes.to_h do |attr|
             [attr, @gapi.send(attr)]
-          end]
+          end
           patch_gapi = API::Bucket.new(**patch_args)
           @gapi = service.patch_bucket name,
                                        patch_gapi,
@@ -2835,6 +3200,26 @@ module Google
           self
         end
 
+        def update_gapi! attributes,
+                         if_metageneration_match: nil,
+                         if_metageneration_not_match: nil
+          attributes = Array(attributes)
+          attributes.flatten!
+          return if attributes.empty?
+          ensure_service!
+          update_args = attributes.to_h do |attr|
+            [attr, @gapi.send(attr)]
+          end
+          update_gapi = API::Bucket.new(**update_args)
+          @gapi = service.update_bucket name,
+                                        update_gapi,
+                                        if_metageneration_match: if_metageneration_match,
+                                        if_metageneration_not_match: if_metageneration_not_match,
+                                        user_project: user_project
+          @lazy = nil
+          self
+        end
+
         ##
         # Raise an error if the file is not found.
         def ensure_io_or_file_exists! file

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

@@ -83,10 +83,12 @@ module Google
                                                 token: @token,
                                                 max: @max,
                                                 versions: @versions,
-                                                user_project: @user_project
+                                                user_project: @user_project,
+                                                match_glob: @match_glob
             File::List.from_gapi gapi, @service, @bucket, @prefix,
                                  @delimiter, @max, @versions,
-                                 user_project: @user_project
+                                 user_project: @user_project,
+                                 match_glob: @match_glob
           end
 
           ##
@@ -163,7 +165,9 @@ module Google
           # Google::Apis::StorageV1::Objects object.
           def self.from_gapi gapi_list, service, bucket = nil, prefix = nil,
                              delimiter = nil, max = nil, versions = nil,
-                             user_project: nil
+                             user_project: nil, match_glob: nil,
+                             include_folders_as_prefixes: nil,
+                             soft_deleted: nil
             files = new(Array(gapi_list.items).map do |gapi_object|
               File.from_gapi gapi_object, service, user_project: user_project
             end)
@@ -176,6 +180,9 @@ module Google
             files.instance_variable_set :@max, max
             files.instance_variable_set :@versions, versions
             files.instance_variable_set :@user_project, user_project
+            files.instance_variable_set :@match_glob, match_glob
+            files.instance_variable_set :@include_folders_as_prefixes, include_folders_as_prefixes
+            files.instance_variable_set :@soft_deleted, soft_deleted
             files
           end
 

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

@@ -48,7 +48,7 @@ module Google
           #
           def ext_path
             path = "/#{@bucket}/#{@path}"
-            escaped = Addressable::URI.escape path
+            escaped = Addressable::URI.encode_component path, Addressable::URI::CharacterClasses::PATH
             special_var = "${filename}"
             # Restore the unencoded `${filename}` variable, if present.
             if path.include? special_var
@@ -60,7 +60,8 @@ module Google
           ##
           # The external url to the file.
           def ext_url
-            "#{GOOGLEAPIS_URL}#{ext_path}"
+            root_url = @service.service.root_url.chomp "/"
+            "#{root_url}#{ext_path}"
           end
 
           def apply_option_defaults options
@@ -91,7 +92,7 @@ module Google
 
           def error_msg attr_name
             "Service account credentials '#{attr_name}' is missing. To generate service account credentials " \
-            "see https://cloud.google.com/iam/docs/service-accounts"
+              "see https://cloud.google.com/iam/docs/service-accounts"
           end
 
           def post_object options
@@ -144,8 +145,8 @@ module Google
 
           def generate_signed_url issuer, signed_string, expires, query
             url = "#{ext_url}?GoogleAccessId=#{url_escape issuer}" \
-              "&Expires=#{expires}" \
-              "&Signature=#{url_escape signed_string}"
+                  "&Expires=#{expires}" \
+                  "&Signature=#{url_escape signed_string}"
 
             query&.each do |name, value|
               url << "&#{url_escape name}=#{url_escape value}"

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

@@ -131,7 +131,7 @@ module Google
           # methods below are public visibility only for unit testing
           # rubocop:disable Style/StringLiterals
           def escape_characters str
-            str.split("").map do |s|
+            str.chars.map do |s|
               if s.ascii_only?
                 case s
                 when "\\"
@@ -207,7 +207,7 @@ module Google
 
           def error_msg attr_name
             "Service account credentials '#{attr_name}' is missing. To generate service account credentials " \
-            "see https://cloud.google.com/iam/docs/service-accounts"
+              "see https://cloud.google.com/iam/docs/service-accounts"
           end
 
           def service_account_signer signer
@@ -243,7 +243,7 @@ module Google
             headers_arr = canonical_headers.map do |k, v|
               [k.downcase, v.strip.gsub(/[^\S\t]+/, " ").gsub(/\t+/, " ")]
             end
-            canonical_headers = Hash[headers_arr]
+            canonical_headers = headers_arr.to_h
             canonical_headers["host"] = host_name virtual_hosted_style, bucket_bound_hostname
 
             canonical_headers = canonical_headers.sort_by(&:first).to_h
@@ -295,13 +295,13 @@ module Google
           ##
           # The external path to the bucket, with trailing slash.
           def bucket_path path_style
-            return "/#{@bucket_name}/" if path_style
+            "/#{@bucket_name}/" if path_style
           end
 
           ##
           # The external url to the file.
           def ext_url scheme, virtual_hosted_style, bucket_bound_hostname
-            url = GOOGLEAPIS_URL.dup
+            url = @service.service.root_url.chomp "/"
             if virtual_hosted_style
               parts = url.split "//"
               parts[1] = "#{@bucket_name}.#{parts[1]}"
@@ -326,7 +326,7 @@ module Google
           #
           def post_object_ext_path
             path = "/#{@bucket_name}/#{@file_name}"
-            escaped = Addressable::URI.escape path
+            escaped = Addressable::URI.encode_component path, Addressable::URI::CharacterClasses::PATH
             special_var = "${filename}"
             # Restore the unencoded `${filename}` variable, if present.
             if path.include? special_var