google-cloud-storage 1.18.1 → 1.44.0

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

@@ -25,12 +25,13 @@ module Google
         def storage_class_for str
           return nil if str.nil?
           return str.map { |s| storage_class_for s } if str.is_a? Array
-          { "durable_reduced_availability" => "DURABLE_REDUCED_AVAILABILITY",
+          { "archive" => "ARCHIVE",
+            "coldline" => "COLDLINE",
             "dra" => "DURABLE_REDUCED_AVAILABILITY",
             "durable" => "DURABLE_REDUCED_AVAILABILITY",
-            "nearline" => "NEARLINE",
-            "coldline" => "COLDLINE",
+            "durable_reduced_availability" => "DURABLE_REDUCED_AVAILABILITY",
             "multi_regional" => "MULTI_REGIONAL",
+            "nearline" => "NEARLINE",
             "regional" => "REGIONAL",
             "standard" => "STANDARD" }[str.to_s.downcase] || str.to_s
         end

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

@@ -38,20 +38,22 @@ module Google
       #   storage.project_id #=> "my-project"
       #
       class Credentials < Google::Auth::Credentials
-        SCOPE = \
-          ["https://www.googleapis.com/auth/devstorage.full_control"].freeze
-        PATH_ENV_VARS = %w[STORAGE_CREDENTIALS
-                           STORAGE_KEYFILE
-                           GOOGLE_CLOUD_CREDENTIALS
-                           GOOGLE_CLOUD_KEYFILE
-                           GCLOUD_KEYFILE].freeze
-        JSON_ENV_VARS = %w[STORAGE_CREDENTIALS_JSON
-                           STORAGE_KEYFILE_JSON
-                           GOOGLE_CLOUD_CREDENTIALS_JSON
-                           GOOGLE_CLOUD_KEYFILE_JSON
-                           GCLOUD_KEYFILE_JSON].freeze
-        DEFAULT_PATHS = \
-          ["~/.config/gcloud/application_default_credentials.json"].freeze
+        SCOPE = ["https://www.googleapis.com/auth/devstorage.full_control"].freeze
+        PATH_ENV_VARS = [
+          "STORAGE_CREDENTIALS",
+          "STORAGE_KEYFILE",
+          "GOOGLE_CLOUD_CREDENTIALS",
+          "GOOGLE_CLOUD_KEYFILE",
+          "GCLOUD_KEYFILE"
+        ].freeze
+        JSON_ENV_VARS = [
+          "STORAGE_CREDENTIALS_JSON",
+          "STORAGE_KEYFILE_JSON",
+          "GOOGLE_CLOUD_CREDENTIALS_JSON",
+          "GOOGLE_CLOUD_KEYFILE_JSON",
+          "GCLOUD_KEYFILE_JSON"
+        ].freeze
+        DEFAULT_PATHS = ["~/.config/gcloud/application_default_credentials.json"].freeze
       end
     end
   end

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

@@ -58,8 +58,13 @@ module Google
       ##
       # # SignedUrlUnavailable Error
       #
-      # This is raised when File#signed_url is unable to generate a URL due to
-      # missing credentials needed to create the URL.
+      # Raised by signed URL methods if the service account credentials
+      # are missing. Service account credentials are acquired by following the
+      # steps in [Service Account Authentication](
+      # https://cloud.google.com/iam/docs/service-accounts).
+      #
+      # @see https://cloud.google.com/storage/docs/access-control/signed-urls Signed URLs
+      #
       class SignedUrlUnavailable < Google::Cloud::Error
       end
     end

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

@@ -190,7 +190,7 @@ module Google
                                             generation: generation,
                                             user_project: user_project
             entity = gapi.entity
-            @owners.push entity unless @owners.nil?
+            @owners&.push entity
             entity
           end
 
@@ -241,7 +241,7 @@ module Google
                                             generation: generation,
                                             user_project: user_project
             entity = gapi.entity
-            @readers.push entity unless @readers.nil?
+            @readers&.push entity
             entity
           end
 
@@ -281,8 +281,8 @@ module Google
             @service.delete_file_acl \
               @bucket, @file, entity,
               generation: generation, user_project: user_project
-            @owners.delete entity  unless @owners.nil?
-            @readers.delete entity unless @readers.nil?
+            @owners&.delete entity
+            @readers&.delete entity
             true
           end
 
@@ -297,6 +297,22 @@ module Google
           # Convenience method to apply the `authenticatedRead` predefined ACL
           # rule to the file.
           #
+          # @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.
+          #
           # @example
           #   require "google/cloud/storage"
           #
@@ -307,8 +323,17 @@ module Google
           #   file = bucket.file "path/to/my-file.ext"
           #   file.acl.auth!
           #
-          def auth!
-            update_predefined_acl! "authenticatedRead"
+          def auth! generation: nil,
+                    if_generation_match: nil,
+                    if_generation_not_match: nil,
+                    if_metageneration_match: nil,
+                    if_metageneration_not_match: nil
+            update_predefined_acl! "authenticatedRead",
+                                   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
           end
           alias authenticatedRead! auth!
           alias auth_read! auth!
@@ -319,6 +344,22 @@ module Google
           # Convenience method to apply the `bucketOwnerFullControl` predefined
           # ACL rule to the file.
           #
+          # @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.
+          #
           # @example
           #   require "google/cloud/storage"
           #
@@ -329,8 +370,17 @@ module Google
           #   file = bucket.file "path/to/my-file.ext"
           #   file.acl.owner_full!
           #
-          def owner_full!
-            update_predefined_acl! "bucketOwnerFullControl"
+          def owner_full! generation: nil,
+                          if_generation_match: nil,
+                          if_generation_not_match: nil,
+                          if_metageneration_match: nil,
+                          if_metageneration_not_match: nil
+            update_predefined_acl! "bucketOwnerFullControl",
+                                   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
           end
           alias bucketOwnerFullControl! owner_full!
 
@@ -338,6 +388,22 @@ module Google
           # Convenience method to apply the `bucketOwnerRead` predefined ACL
           # rule to the file.
           #
+          # @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.
+          #
           # @example
           #   require "google/cloud/storage"
           #
@@ -348,8 +414,17 @@ module Google
           #   file = bucket.file "path/to/my-file.ext"
           #   file.acl.owner_read!
           #
-          def owner_read!
-            update_predefined_acl! "bucketOwnerRead"
+          def owner_read! generation: nil,
+                          if_generation_match: nil,
+                          if_generation_not_match: nil,
+                          if_metageneration_match: nil,
+                          if_metageneration_not_match: nil
+            update_predefined_acl! "bucketOwnerRead",
+                                   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
           end
           alias bucketOwnerRead! owner_read!
 
@@ -357,6 +432,22 @@ module Google
           # Convenience method to apply the `private` predefined ACL
           # rule to the file.
           #
+          # @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.
+          #
           # @example
           #   require "google/cloud/storage"
           #
@@ -367,14 +458,39 @@ module Google
           #   file = bucket.file "path/to/my-file.ext"
           #   file.acl.private!
           #
-          def private!
-            update_predefined_acl! "private"
+          def private! generation: nil,
+                       if_generation_match: nil,
+                       if_generation_not_match: nil,
+                       if_metageneration_match: nil,
+                       if_metageneration_not_match: nil
+            update_predefined_acl! "private",
+                                   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
           end
 
           ##
           # Convenience method to apply the `projectPrivate` predefined ACL
           # rule to the file.
           #
+          # @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.
+          #
           # @example
           #   require "google/cloud/storage"
           #
@@ -385,8 +501,17 @@ module Google
           #   file = bucket.file "path/to/my-file.ext"
           #   file.acl.project_private!
           #
-          def project_private!
-            update_predefined_acl! "projectPrivate"
+          def project_private! generation: nil,
+                               if_generation_match: nil,
+                               if_generation_not_match: nil,
+                               if_metageneration_match: nil,
+                               if_metageneration_not_match: nil
+            update_predefined_acl! "projectPrivate",
+                                   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
           end
           alias projectPrivate! project_private!
 
@@ -394,6 +519,22 @@ module Google
           # Convenience method to apply the `publicRead` predefined ACL
           # rule to the file.
           #
+          # @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.
+          #
           # @example
           #   require "google/cloud/storage"
           #
@@ -404,8 +545,17 @@ module Google
           #   file = bucket.file "path/to/my-file.ext"
           #   file.acl.public!
           #
-          def public!
-            update_predefined_acl! "publicRead"
+          def public! generation: nil,
+                      if_generation_match: nil,
+                      if_generation_not_match: nil,
+                      if_metageneration_match: nil,
+                      if_metageneration_not_match: nil
+            update_predefined_acl! "publicRead",
+                                   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
           end
           alias publicRead! public!
           alias public_read! public!
@@ -418,9 +568,21 @@ module Google
             self
           end
 
-          def update_predefined_acl! acl_role
+          def update_predefined_acl! acl_role,
+                                     generation: nil,
+                                     if_generation_match: nil,
+                                     if_generation_not_match: nil,
+                                     if_metageneration_match: nil,
+                                     if_metageneration_not_match: nil
             patched_file = Google::Apis::StorageV1::Object.new acl: []
-            @service.patch_file @bucket, @file, patched_file,
+            @service.patch_file @bucket,
+                                @file,
+                                patched_file,
+                                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,
                                 predefined_acl: acl_role,
                                 user_project: user_project
             clear!
@@ -428,8 +590,7 @@ module Google
 
           def entities_from_acls acls, role
             selected = acls.select { |acl| acl.role == role }
-            entities = selected.map(&:entity)
-            entities
+            selected.map(&:entity)
           end
         end
       end

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

@@ -77,11 +77,13 @@ module Google
           def next
             return nil unless next?
             ensure_service!
-            options = {
-              prefix: @prefix, delimiter: @delimiter, token: @token, max: @max,
-              versions: @versions, user_project: @user_project
-            }
-            gapi = @service.list_files @bucket, options
+
+            gapi = @service.list_files @bucket, prefix: @prefix,
+                                                delimiter: @delimiter,
+                                                token: @token,
+                                                max: @max,
+                                                versions: @versions,
+                                                user_project: @user_project
             File::List.from_gapi gapi, @service, @bucket, @prefix,
                                  @delimiter, @max, @versions,
                                  user_project: @user_project
@@ -139,17 +141,17 @@ module Google
           #     puts file.name
           #   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/file/signer_v2.rb

@@ -41,9 +41,20 @@ module Google
           end
 
           ##
-          # The external path to the file.
+          # The external path to the file, URI-encoded.
+          # Will not URI encode the special `${filename}` variable.
+          # "You can also use the ${filename} variable..."
+          # https://cloud.google.com/storage/docs/xml-api/post-object
+          #
           def ext_path
-            Addressable::URI.escape "/#{@bucket}/#{@path}"
+            path = "/#{@bucket}/#{@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
+              return escaped.gsub "$%7Bfilename%7D", special_var
+            end
+            escaped
           end
 
           ##
@@ -66,13 +77,21 @@ module Google
           end
 
           def determine_signing_key options = {}
-            options[:signing_key] || options[:private_key] ||
-              @service.credentials.signing_key
+            signing_key = options[:signing_key] || options[:private_key] ||
+                          options[:signer] || @service.credentials.signing_key
+            raise SignedUrlUnavailable, error_msg("signing_key (private_key, signer)") unless signing_key
+            signing_key
           end
 
           def determine_issuer options = {}
-            options[:issuer] || options[:client_email] ||
-              @service.credentials.issuer
+            issuer = options[:issuer] || options[:client_email] || @service.credentials.issuer
+            raise SignedUrlUnavailable, error_msg("issuer (client_email)") unless issuer
+            issuer
+          end
+
+          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"
           end
 
           def post_object options
@@ -88,8 +107,6 @@ module Google
             i = determine_issuer options
             s = determine_signing_key options
 
-            raise SignedUrlUnavailable unless i && s
-
             policy_str = p.to_json
             policy = Base64.strict_encode64(policy_str).delete "\n"
 
@@ -108,18 +125,21 @@ module Google
             i = determine_issuer options
             s = determine_signing_key options
 
-            raise SignedUrlUnavailable unless i && s
-
             sig = generate_signature s, signature_str(options)
             generate_signed_url i, sig, options[:expires], options[:query]
           end
 
           def generate_signature signing_key, secret
-            unless signing_key.respond_to? :sign
-              signing_key = OpenSSL::PKey::RSA.new signing_key
+            unencoded_signature = ""
+            if signing_key.is_a? Proc
+              unencoded_signature = signing_key.call secret
+            else
+              unless signing_key.respond_to? :sign
+                signing_key = OpenSSL::PKey::RSA.new signing_key
+              end
+              unencoded_signature = signing_key.sign OpenSSL::Digest::SHA256.new, secret
             end
-            signature = signing_key.sign OpenSSL::Digest::SHA256.new, secret
-            Base64.strict_encode64(signature).delete "\n"
+            Base64.strict_encode64(unencoded_signature).delete "\n"
           end
 
           def generate_signed_url issuer, signed_string, expires, query
@@ -127,10 +147,8 @@ module Google
               "&Expires=#{expires}" \
               "&Signature=#{url_escape signed_string}"
 
-            if query
-              query.each do |name, value|
-                url << "&#{url_escape name}=#{url_escape value}"
-              end
+            query&.each do |name, value|
+              url << "&#{url_escape name}=#{url_escape value}"
             end
 
             url