google-cloud-storage 1.18.1 → 1.44.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
@@ -355,6 +370,32 @@ module Google
           update_gapi! :content_type
         end
 
+        ##
+        # A custom time specified by the user for the file, or `nil`.
+        #
+        # @return [DateTime, nil]
+        #
+        def custom_time
+          @gapi.custom_time
+        end
+
+        ##
+        # Updates the custom time specified by the user for the file. Once set,
+        # custom_time can't be unset, and it can only be changed to a time in the
+        # 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.
+        #
+        def custom_time= custom_time
+          @gapi.custom_time = custom_time
+          update_gapi! :custom_time
+        end
+
         ##
         # A hash of custom, user-provided web-safe keys and arbitrary string
         # values that will returned with requests for the file as "x-goog-meta-"
@@ -373,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.
         #
@@ -389,7 +433,8 @@ module Google
         # You can use this SHA256 hash to uniquely identify the AES-256
         # encryption key required to decrypt this file.
         #
-        # @return [String]
+        # @return [String, nil] The encoded SHA256 hash, or `nil` if there is
+        #   no customer-supplied encryption key for this file.
         #
         def encryption_key_sha256
           return nil unless @gapi.customer_encryption
@@ -428,10 +473,10 @@ module Google
         # Rewrites the file with a new storage class, which determines the SLA
         # and the cost of storage. Accepted values include:
         #
-        # * `:multi_regional`
-        # * `:regional`
+        # * `:standard`
         # * `:nearline`
         # * `:coldline`
+        # * `:archive`
         #
         # as well as the equivalent strings returned by {File#storage_class} or
         # {Bucket#storage_class}. For more information, see [Storage
@@ -441,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
@@ -481,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
@@ -509,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"
         #
@@ -619,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"
         #
@@ -657,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"
         #
@@ -746,8 +806,25 @@ module Google
         # Updates the file with changes made in the given block in a single
         # PATCH request. The following attributes may be set: {#cache_control=},
         # {#content_disposition=}, {#content_encoding=}, {#content_language=},
-        # {#content_type=}, and {#metadata=}. The {#metadata} hash accessible in
-        # the block is completely mutable and will be included in the request.
+        # {#content_type=}, {#custom_time=} and {#metadata=}. The {#metadata} hash
+        # 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.
         #
         # @yield [file] a block yielding a delegate object for updating the file
         #
@@ -766,19 +843,43 @@ module Google
         #     f.content_encoding = "deflate"
         #     f.content_language = "de"
         #     f.content_type = "application/json"
+        #     f.custom_time = DateTime.new 2025, 12, 31
         #     f.metadata["player"] = "Bob"
         #     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
           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
         end
 
         ##
-        # Download the file's contents to a local file or an File-like object.
+        # Downloads the file's contents to a local file or an File-like object.
         #
         # By default, the download is verified by calculating the MD5 digest.
         #
@@ -938,8 +1039,8 @@ module Google
           end
           file, resp =
             service.download_file bucket, name, path,
-                                  key: encryption_key, range: range,
-                                  user_project: user_project
+                                  generation: generation, key: encryption_key,
+                                  range: range, user_project: user_project
           # FIX: downloading with encryption key will return nil
           file ||= ::File.new path
           verify = :none if range
@@ -952,7 +1053,15 @@ module Google
         end
 
         ##
-        # Copy the file to a new location.
+        # Copies the file to a new location. Metadata excluding ACL from the source
+        # object will be copied to the destination object unless a block is provided.
+        #
+        # If an optional block for updating is provided, only the updates made in
+        # this block will appear in the destination object, and other metadata
+        # fields in the destination object will not be copied. To copy the other
+        # source file metadata fields while updating destination fields in a
+        # block, use the `force_copy_metadata: true` flag, and the client library
+        # will copy metadata from source metadata into the copy request.
         #
         # If a [customer-supplied encryption
         # key](https://cloud.google.com/storage/docs/encryption#customer-supplied)
@@ -987,6 +1096,19 @@ module Google
         # @param [String] encryption_key Optional. The customer-supplied,
         #   AES-256 encryption key used to encrypt the file, if one was provided
         #   to {Bucket#create_file}.
+        # @param [Boolean] force_copy_metadata Optional. If `true` and if updates
+        #   are made in a block, the following fields will be copied from the
+        #   source file to the destination file (except when changed by updates):
+        #
+        #   * `cache_control`
+        #   * `content_disposition`
+        #   * `content_encoding`
+        #   * `content_language`
+        #   * `content_type`
+        #   * `metadata`
+        #
+        #   If `nil` or `false`, only the updates made in the yielded block will
+        #   be applied to the destination object. The default is `nil`.
         # @yield [file] a block yielding a delegate object for updating
         #
         # @return [Google::Cloud::Storage::File]
@@ -1036,12 +1158,13 @@ module Google
         #     f.metadata["copied_from"] = "#{file.bucket}/#{file.name}"
         #   end
         #
-        def copy dest_bucket_or_path, dest_path = nil,
-                 acl: nil, generation: nil, encryption_key: nil
+        def copy dest_bucket_or_path, dest_path = nil, acl: nil, generation: nil, encryption_key: nil,
+                 force_copy_metadata: nil
           rewrite dest_bucket_or_path, dest_path,
                   acl: acl, generation: generation,
                   encryption_key: encryption_key,
-                  new_encryption_key: encryption_key do |updater|
+                  new_encryption_key: encryption_key,
+                  force_copy_metadata: force_copy_metadata do |updater|
             yield updater if block_given?
           end
         end
@@ -1049,7 +1172,15 @@ module Google
         ##
         # [Rewrites](https://cloud.google.com/storage/docs/json_api/v1/objects/rewrite)
         # the file to a new location. Or the same location can be provided to
-        # rewrite the file in place.
+        # rewrite the file in place. Metadata from the source object will
+        # be copied to the destination object unless a block is provided.
+        #
+        # If an optional block for updating is provided, only the updates made in
+        # this block will appear in the destination object, and other metadata
+        # fields in the destination object will not be copied. To copy the other
+        # source file metadata fields while updating destination fields in a
+        # block, use the `force_copy_metadata: true` flag, and the client library
+        # will copy metadata from source metadata into the copy request.
         #
         # If a [customer-supplied encryption
         # key](https://cloud.google.com/storage/docs/encryption#customer-supplied)
@@ -1082,6 +1213,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.
@@ -1097,6 +1249,19 @@ module Google
         #   the same location as the bucket.The Service Account associated with
         #   your project requires access to this encryption key. Do not provide
         #   if `new_encryption_key` is used.
+        # @param [Boolean] force_copy_metadata Optional. If `true` and if updates
+        #   are made in a block, the following fields will be copied from the
+        #   source file to the destination file (except when changed by updates):
+        #
+        #   * `cache_control`
+        #   * `content_disposition`
+        #   * `content_encoding`
+        #   * `content_language`
+        #   * `content_type`
+        #   * `metadata`
+        #
+        #   If `nil` or `false`, only the updates made in the yielded block will
+        #   be applied to the destination object. The default is `nil`.
         # @yield [file] a block yielding a delegate object for updating
         #
         # @return [Google::Cloud::Storage::File]
@@ -1161,7 +1326,7 @@ module Google
         #   cipher.encrypt
         #   new_key = cipher.random_key
         #
-        #   file = bucket.file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext", encryption_key: old_key
         #   file.rewrite "new-destination-bucket",
         #                "path/to/destination/file.ext",
         #                encryption_key: old_key,
@@ -1182,7 +1347,7 @@ module Google
         #   # Old customer-supplied key was stored securely for later use.
         #   old_key = "y\x03\"\x0E\xB6\xD3\x9B\x0E\xAB*\x19\xFAv\xDEY\xBEI..."
         #
-        #   file = bucket.file "path/to/my-file.ext"
+        #   file = bucket.file "path/to/my-file.ext", encryption_key: old_key
         #   file.rewrite "new-destination-bucket",
         #                "path/to/destination/file.ext",
         #                encryption_key: old_key,
@@ -1190,27 +1355,51 @@ 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
+        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?
-            updater = Updater.new gapi
+            updater = Updater.new gapi.dup
             yield updater
             updater.check_for_changed_metadata!
             if updater.updates.any?
-              update_gapi = gapi_from_attrs updater.updates
+              attributes = force_copy_metadata ? (Updater::COPY_ATTRS + updater.updates).uniq : updater.updates
+              update_gapi = self.class.gapi_from_attrs updater.gapi, attributes
             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,
@@ -1307,6 +1496,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
@@ -1339,11 +1542,21 @@ 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
 
@@ -1400,7 +1613,7 @@ module Google
         # A {SignedUrlUnavailable} is raised if the service account credentials
         # are missing. Service account credentials are acquired by following the
         # steps in [Service Account Authentication](
-        # https://cloud.google.com/storage/docs/authentication#service_accounts).
+        # https://cloud.google.com/iam/docs/service-accounts).
         #
         # @see https://cloud.google.com/storage/docs/access-control/signed-urls
         #   Signed URLs guide
@@ -1425,10 +1638,22 @@ module Google
         #   use the signed URL.
         # @param [String] issuer Service Account's Client Email.
         # @param [String] client_email Service Account's Client Email.
-        # @param [OpenSSL::PKey::RSA, String] signing_key Service Account's
-        #   Private Key.
-        # @param [OpenSSL::PKey::RSA, String] private_key Service Account's
-        #   Private Key.
+        # @param [OpenSSL::PKey::RSA, String, Proc] signing_key Service Account's
+        #   Private Key or a Proc that accepts a single String parameter and returns a
+        #   RSA SHA256 signature using a valid Google Service Account Private Key.
+        # @param [OpenSSL::PKey::RSA, String, Proc] private_key Service Account's
+        #   Private Key or a Proc that accepts a single String parameter and returns a
+        #   RSA SHA256 signature using a valid Google Service Account Private Key.
+        # @param [OpenSSL::PKey::RSA, String, Proc] signer Service Account's
+        #   Private Key or a Proc that accepts a single String parameter and returns a
+        #   RSA SHA256 signature using a valid Google Service Account Private Key.
+        #
+        #   When using this method in environments such as GAE Flexible Environment,
+        #   GKE, or Cloud Functions where the private key is unavailable, it may be
+        #   necessary to provide a Proc (or lambda) via the signer parameter. This
+        #   Proc should return a signature created using a RPC call to the
+        #   [Service Account Credentials signBlob](https://cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signBlob)
+        #   method as shown in the example below.
         # @param [Hash] query Query string parameters to include in the signed
         #   URL. The given parameters are not verified by the signature.
         #
@@ -1437,11 +1662,29 @@ module Google
         #   using the URL, but only when the file resource is missing the
         #   corresponding values. (These values can be permanently set using
         #   {#content_disposition=} and {#content_type=}.)
+        # @param [String] scheme The URL scheme. The default value is `HTTPS`.
+        # @param [Boolean] virtual_hosted_style Whether to use a virtual hosted-style
+        #   hostname, which adds the bucket into the host portion of the URI rather
+        #   than the path, e.g. `https://mybucket.storage.googleapis.com/...`.
+        #   For V4 signing, this also sets the `host` header in the canonicalized
+        #   extension headers to the virtual hosted-style host, unless that header is
+        #   supplied via the `headers` param. The default value of `false` uses the
+        #   form of `https://storage.googleapis.com/mybucket`.
+        # @param [String] bucket_bound_hostname Use a bucket-bound hostname, which
+        #   replaces the `storage.googleapis.com` host with the name of a `CNAME`
+        #   bucket, e.g. a bucket named `gcs-subdomain.my.domain.tld`, or a Google
+        #   Cloud Load Balancer which routes to a bucket you own, e.g.
+        #   `my-load-balancer-domain.tld`.
         # @param [Symbol, String] version The version of the signed credential
         #   to create. Must be one of `:v2` or `:v4`. The default value is
         #   `:v2`.
         #
-        # @return [String]
+        # @return [String] The signed URL.
+        #
+        # @raise [SignedUrlUnavailable] 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).
         #
         # @example
         #   require "google/cloud/storage"
@@ -1461,7 +1704,7 @@ module Google
         #   file = bucket.file "avatars/heidi/400x400.png"
         #   shared_url = file.signed_url expires: 300, # 5 minutes from now
         #                                version: :v4
-
+        #
         # @example Using the `issuer` and `signing_key` options:
         #   require "google/cloud/storage"
         #
@@ -1501,28 +1744,85 @@ module Google
         #   # Send the `x-goog-resumable:start` header and the content type
         #   # with the resumable upload POST request.
         #
-        def signed_url method: nil, expires: nil, content_type: nil,
-                       content_md5: nil, headers: nil, issuer: nil,
-                       client_email: nil, signing_key: nil, private_key: nil,
-                       query: nil, version: nil
+        # @example Using Cloud IAMCredentials signBlob to create the signature:
+        #   require "google/cloud/storage"
+        #   require "google/apis/iamcredentials_v1"
+        #   require "googleauth"
+        #
+        #   # Issuer is the service account email that the Signed URL will be signed with
+        #   # and any permission granted in the Signed URL must be granted to the
+        #   # Google Service Account.
+        #   issuer = "service-account@project-id.iam.gserviceaccount.com"
+        #
+        #   # Create a lambda that accepts the string_to_sign
+        #   signer = lambda do |string_to_sign|
+        #     IAMCredentials = Google::Apis::IamcredentialsV1
+        #     iam_client = IAMCredentials::IAMCredentialsService.new
+        #
+        #     # Get the environment configured authorization
+        #     scopes = ["https://www.googleapis.com/auth/iam"]
+        #     iam_client.authorization = Google::Auth.get_application_default scopes
+        #
+        #     request = Google::Apis::IamcredentialsV1::SignBlobRequest.new(
+        #       payload: string_to_sign
+        #     )
+        #     resource = "projects/-/serviceAccounts/#{issuer}"
+        #     response = iam_client.sign_service_account_blob resource, request
+        #     response.signed_blob
+        #   end
+        #
+        #   storage = Google::Cloud::Storage.new
+        #
+        #   bucket = storage.bucket "my-todo-app"
+        #   file = bucket.file "avatars/heidi/400x400.png", skip_lookup: true
+        #   url = file.signed_url method: "GET", issuer: issuer,
+        #                         signer: signer
+        #
+        def signed_url method: "GET",
+                       expires: nil,
+                       content_type: nil,
+                       content_md5: nil,
+                       headers: nil,
+                       issuer: nil,
+                       client_email: nil,
+                       signing_key: nil,
+                       private_key: nil,
+                       signer: nil,
+                       query: nil,
+                       scheme: "HTTPS",
+                       virtual_hosted_style: nil,
+                       bucket_bound_hostname: nil,
+                       version: nil
           ensure_service!
           version ||= :v2
           case version.to_sym
           when :v2
-            signer = File::SignerV2.from_file self
-            signer.signed_url method: method, expires: expires,
-                              headers: headers, content_type: content_type,
-                              content_md5: content_md5, issuer: issuer,
-                              client_email: client_email,
-                              signing_key: signing_key,
-                              private_key: private_key, query: query
+            sign = File::SignerV2.from_file self
+            sign.signed_url method: method,
+                            expires: expires,
+                            headers: headers,
+                            content_type: content_type,
+                            content_md5: content_md5,
+                            issuer: issuer,
+                            client_email: client_email,
+                            signing_key: signing_key,
+                            private_key: private_key,
+                            signer: signer,
+                            query: query
           when :v4
-            signer = File::SignerV4.from_file self
-            signer.signed_url method: method, expires: expires,
-                              headers: headers, issuer: issuer,
-                              client_email: client_email,
-                              signing_key: signing_key,
-                              private_key: private_key, query: query
+            sign = File::SignerV4.from_file self
+            sign.signed_url method: method,
+                            expires: expires,
+                            headers: headers,
+                            issuer: issuer,
+                            client_email: client_email,
+                            signing_key: signing_key,
+                            private_key: private_key,
+                            signer: signer,
+                            query: query,
+                            scheme: scheme,
+                            virtual_hosted_style: virtual_hosted_style,
+                            bucket_bound_hostname: bucket_bound_hostname
           else
             raise ArgumentError, "version '#{version}' not supported"
           end
@@ -1679,6 +1979,21 @@ module Google
           end
         end
 
+        ##
+        # @private
+        #
+        def self.gapi_from_attrs gapi, attributes
+          attributes.flatten!
+          return nil if attributes.empty?
+          attr_params = Hash[attributes.map do |attr|
+                               [attr, gapi.send(attr)]
+                             end]
+          # Sending nil metadata results in an Apiary runtime error:
+          # NoMethodError: undefined method `each' for nil:NilClass
+          attr_params.reject! { |k, v| k == :metadata && v.nil? }
+          Google::Apis::StorageV1::Object.new(**attr_params)
+        end
+
         protected
 
         ##
@@ -1695,53 +2010,89 @@ 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
+          attributes = Array(attributes)
           attributes.flatten!
           return if attributes.empty?
-          update_gapi = gapi_from_attrs attributes
+          update_gapi = self.class.gapi_from_attrs @gapi, attributes
           return if update_gapi.nil?
 
           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
                   end
         end
 
-        def gapi_from_attrs *attributes
-          attributes.flatten!
-          return nil if attributes.empty?
-          attr_params = Hash[attributes.map do |attr|
-            [attr, @gapi.send(attr)]
-          end]
-          Google::Apis::StorageV1::Object.new attr_params
-        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
+            bucket, name, new_bucket, new_name, updated_gapi, **options
           until resp.done
             sleep 1
             retry_options = options.merge token: resp.rewrite_token
             resp = service.rewrite_file \
-              bucket, name, new_bucket, new_name, updated_gapi, retry_options
+              bucket, name, new_bucket, new_name, updated_gapi, **retry_options
           end
           resp.resource
         end
@@ -1792,11 +2143,26 @@ module Google
         # Yielded to a block to accumulate changes for a patch request.
         class Updater < File
           # @private
-          attr_reader :updates
+          attr_reader :updates, :gapi
+
+          ##
+          # @private
+          # Whitelist of Google::Apis::StorageV1::Object attributes to be
+          # copied when File#copy or File#rewrite is called with
+          # `force_copy_metadata: true`.
+          COPY_ATTRS = [
+            :cache_control,
+            :content_disposition,
+            :content_encoding,
+            :content_language,
+            :content_type,
+            :metadata
+          ].freeze
 
           ##
           # @private Create an Updater object.
           def initialize gapi
+            super()
             @updates = []
             @gapi = gapi
             @metadata ||= @gapi.metadata.to_h.dup