google-cloud-storage 1.26.1 → 1.29.1

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

@@ -105,6 +105,21 @@ module Google
           #   only the date part (for instance, "2013-01-15"). This condition is
           #   satisfied when a file is created before midnight of the specified
           #   date in UTC.
+          # @param [String,Date] custom_time_before A date in RFC 3339 format with
+          #   only the date part (for instance, "2013-01-15"). This condition is
+          #   satisfied when the custom time on an object is before this date in UTC.
+          # @param [Integer] days_since_custom_time Represents the number of
+          #   days elapsed since the user-specified timestamp set on an object.
+          #   The condition is satisfied if the days elapsed is at least this
+          #   number. If no custom timestamp is specified on an object, the
+          #   condition does not apply.
+          # @param [Integer] days_since_noncurrent_time Represents the number of
+          #   days elapsed since the noncurrent timestamp of an object. The
+          #   condition is satisfied if the days elapsed is at least this number.
+          #   The value of the field must be a nonnegative integer. If it's zero,
+          #   the object version will become eligible for Lifecycle action as
+          #   soon as it becomes noncurrent. Relevant only for versioning-enabled
+          #   buckets. (See {Bucket#versioning?})
           # @param [Boolean] is_live Relevant only for versioned files. If the
           #   value is `true`, this condition matches live files; if the value
           #   is `false`, it matches archived files.
@@ -115,6 +130,10 @@ module Google
           #   `DURABLE_REDUCED_AVAILABILITY` are supported as legacy storage
           #   classes. Arguments will be converted from symbols and lower-case
           #   to upper-case strings.
+          # @param [String,Date] noncurrent_time_before A date in RFC 3339 format
+          #   with only the date part (for instance, "2013-01-15"). This condition
+          #   is satisfied when the noncurrent time on an object is before this
+          #   date in UTC. This condition is relevant only for versioned objects.
           # @param [Integer] num_newer_versions Relevant only for versioned
           #   files. If the value is N, this condition is satisfied when there
           #   are at least N versions (including the live version) newer than
@@ -129,16 +148,29 @@ module Google
           #     b.lifecycle.add_set_storage_class_rule "COLDLINE", age: 10
           #   end
           #
-          def add_set_storage_class_rule storage_class, age: nil,
-                                         created_before: nil, is_live: nil,
+          def add_set_storage_class_rule storage_class,
+                                         age: nil,
+                                         created_before: nil,
+                                         custom_time_before: nil,
+                                         days_since_custom_time: nil,
+                                         days_since_noncurrent_time: nil,
+                                         is_live: nil,
                                          matches_storage_class: nil,
+                                         noncurrent_time_before: nil,
                                          num_newer_versions: nil
-            push Rule.new \
+            push Rule.new(
               "SetStorageClass",
               storage_class: storage_class_for(storage_class),
-              age: age, created_before: created_before, is_live: is_live,
+              age: age,
+              created_before: created_before,
+              custom_time_before: custom_time_before,
+              days_since_custom_time: days_since_custom_time,
+              days_since_noncurrent_time: days_since_noncurrent_time,
+              is_live: is_live,
               matches_storage_class: storage_class_for(matches_storage_class),
+              noncurrent_time_before: noncurrent_time_before,
               num_newer_versions: num_newer_versions
+            )
           end
 
           ##
@@ -156,6 +188,21 @@ module Google
           #   only the date part (for instance, "2013-01-15"). This condition is
           #   satisfied when a file is created before midnight of the specified
           #   date in UTC.
+          # @param [String,Date] custom_time_before A date in RFC 3339 format with
+          #   only the date part (for instance, "2013-01-15"). This condition is
+          #   satisfied when the custom time on an object is before this date in UTC.
+          # @param [Integer] days_since_custom_time Represents the number of
+          #   days elapsed since the user-specified timestamp set on an object.
+          #   The condition is satisfied if the days elapsed is at least this
+          #   number. If no custom timestamp is specified on an object, the
+          #   condition does not apply.
+          # @param [Integer] days_since_noncurrent_time Represents the number of
+          #   days elapsed since the noncurrent timestamp of an object. The
+          #   condition is satisfied if the days elapsed is at least this number.
+          #   The value of the field must be a nonnegative integer. If it's zero,
+          #   the object version will become eligible for Lifecycle action as
+          #   soon as it becomes noncurrent. Relevant only for versioning-enabled
+          #   buckets. (See {Bucket#versioning?})
           # @param [Boolean] is_live Relevant only for versioned files. If the
           #   value is `true`, this condition matches live files; if the value
           #   is `false`, it matches archived files.
@@ -166,6 +213,10 @@ module Google
           #   `DURABLE_REDUCED_AVAILABILITY` are supported as legacy storage
           #   classes. Arguments will be converted from symbols and lower-case
           #   to upper-case strings.
+          # @param [String,Date] noncurrent_time_before A date in RFC 3339 format
+          #   with only the date part (for instance, "2013-01-15"). This condition
+          #   is satisfied when the noncurrent time on an object is before this
+          #   date in UTC. This condition is relevant only for versioned objects.
           # @param [Integer] num_newer_versions Relevant only for versioned
           #   files. If the value is N, this condition is satisfied when there
           #   are at least N versions (including the live version) newer than
@@ -180,14 +231,27 @@ module Google
           #     b.lifecycle.add_delete_rule age: 30, is_live: false
           #   end
           #
-          def add_delete_rule age: nil, created_before: nil, is_live: nil,
+          def add_delete_rule age: nil,
+                              created_before: nil,
+                              custom_time_before: nil,
+                              days_since_custom_time: nil,
+                              days_since_noncurrent_time: nil,
+                              is_live: nil,
                               matches_storage_class: nil,
+                              noncurrent_time_before: nil,
                               num_newer_versions: nil
-            push Rule.new \
+            push Rule.new(
               "Delete",
-              age: age, created_before: created_before, is_live: is_live,
+              age: age,
+              created_before: created_before,
+              custom_time_before: custom_time_before,
+              days_since_custom_time: days_since_custom_time,
+              days_since_noncurrent_time: days_since_noncurrent_time,
+              is_live: is_live,
               matches_storage_class: storage_class_for(matches_storage_class),
+              noncurrent_time_before: noncurrent_time_before,
               num_newer_versions: num_newer_versions
+            )
           end
 
           # @private
@@ -231,10 +295,26 @@ module Google
           #   action. Required only if the action is `SetStorageClass`.
           # @attr [Integer] age The age of a file (in days). This condition is
           #   satisfied when a file reaches the specified age.
-          # @attr [String,Date] created_before A date in RFC 3339 format with
+          # @attr [String,Date,nil] created_before A date in RFC 3339 format with
           #   only the date part (for instance, "2013-01-15"). This condition is
           #   satisfied when a file is created before midnight of the specified
-          #   date in UTC.
+          #   date in UTC. When returned by the service, a non-empty value will
+          #   always be a Date object.
+          # @attr [String,Date,nil] custom_time_before A date in RFC 3339 format with
+          #   only the date part (for instance, "2013-01-15"). This condition is
+          #   satisfied when the custom time on an object is before this date in UTC.
+          # @attr [Integer,nil] days_since_custom_time Represents the number of
+          #   days elapsed since the user-specified timestamp set on an object.
+          #   The condition is satisfied if the days elapsed is at least this
+          #   number. If no custom timestamp is specified on an object, the
+          #   condition does not apply.
+          # @attr [Integer] days_since_noncurrent_time Represents the number of
+          #   days elapsed since the noncurrent timestamp of an object. The
+          #   condition is satisfied if the days elapsed is at least this number.
+          #   The value of the field must be a nonnegative integer. If it's zero,
+          #   the object version will become eligible for Lifecycle action as
+          #   soon as it becomes noncurrent. Relevant only for versioning-enabled
+          #   buckets. (See {Bucket#versioning?})
           # @attr [Boolean] is_live Relevant only for versioned files. If the
           #   value is `true`, this condition matches live files; if the value
           #   is `false`, it matches archived files.
@@ -243,6 +323,12 @@ module Google
           #   Values include `STANDARD`, `NEARLINE`, `COLDLINE`, and `ARCHIVE`.
           #   `REGIONAL`, `MULTI_REGIONAL`, and `DURABLE_REDUCED_AVAILABILITY`
           #   are supported as legacy storage classes.
+          # @attr [String,Date,nil] noncurrent_time_before A date in RFC 3339 format
+          #   with only the date part (for instance, "2013-01-15"). This condition
+          #   is satisfied when the noncurrent time on an object is before this
+          #   date in UTC. This condition is relevant only for versioned objects.
+          #   When returned by the service, a non-empty value will always be a
+          #   Date object.
           # @attr [Integer] num_newer_versions Relevant only for versioned
           #   files. If the value is N, this condition is satisfied when there
           #   are at least N versions (including the live version) newer than
@@ -285,28 +371,57 @@ module Google
           #   end
           #
           class Rule
-            attr_accessor :action, :storage_class, :age, :created_before,
-                          :is_live, :matches_storage_class, :num_newer_versions
+            attr_accessor :action,
+                          :storage_class,
+                          :age,
+                          :created_before,
+                          :custom_time_before,
+                          :days_since_custom_time,
+                          :days_since_noncurrent_time,
+                          :is_live,
+                          :matches_storage_class,
+                          :noncurrent_time_before,
+                          :num_newer_versions
 
             # @private
-            def initialize action, storage_class: nil, age: nil,
-                           created_before: nil, is_live: nil,
-                           matches_storage_class: nil, num_newer_versions: nil
+            def initialize action,
+                           storage_class: nil,
+                           age: nil,
+                           created_before: nil,
+                           custom_time_before: nil,
+                           days_since_custom_time: nil,
+                           days_since_noncurrent_time: nil,
+                           is_live: nil,
+                           matches_storage_class: nil,
+                           noncurrent_time_before: nil,
+                           num_newer_versions: nil
               @action = action
               @storage_class = storage_class
               @age = age
               @created_before = created_before
+              @custom_time_before = custom_time_before
+              @days_since_custom_time = days_since_custom_time
+              @days_since_noncurrent_time = days_since_noncurrent_time
               @is_live = is_live
               @matches_storage_class = Array(matches_storage_class)
+              @noncurrent_time_before = noncurrent_time_before
               @num_newer_versions = num_newer_versions
             end
 
             # @private
             # @return [Google::Apis::StorageV1::Bucket::Lifecycle]
             def to_gapi
-              condition = condition_gapi(age, created_before, is_live,
-                                         matches_storage_class,
-                                         num_newer_versions)
+              condition = condition_gapi(
+                age,
+                created_before,
+                custom_time_before,
+                days_since_custom_time,
+                days_since_noncurrent_time,
+                is_live,
+                matches_storage_class,
+                noncurrent_time_before,
+                num_newer_versions
+              )
               Google::Apis::StorageV1::Bucket::Lifecycle::Rule.new(
                 action: action_gapi(action, storage_class),
                 condition: condition
@@ -316,18 +431,30 @@ module Google
             # @private
             def action_gapi action, storage_class
               Google::Apis::StorageV1::Bucket::Lifecycle::Rule::Action.new(
-                type: action, storage_class: storage_class
+                type: action,
+                storage_class: storage_class
               )
             end
 
             # @private
-            def condition_gapi age, created_before, is_live,
-                               matches_storage_class, num_newer_versions
+            def condition_gapi age,
+                               created_before,
+                               custom_time_before,
+                               days_since_custom_time,
+                               days_since_noncurrent_time,
+                               is_live,
+                               matches_storage_class,
+                               noncurrent_time_before,
+                               num_newer_versions
               Google::Apis::StorageV1::Bucket::Lifecycle::Rule::Condition.new(
                 age: age,
                 created_before: created_before,
+                custom_time_before: custom_time_before,
+                days_since_custom_time: days_since_custom_time,
+                days_since_noncurrent_time: days_since_noncurrent_time,
                 is_live: is_live,
                 matches_storage_class: Array(matches_storage_class),
+                noncurrent_time_before: noncurrent_time_before,
                 num_newer_versions: num_newer_versions
               )
             end
@@ -337,12 +464,19 @@ module Google
             def self.from_gapi gapi
               action = gapi.action
               c = gapi.condition
-              new action.type, storage_class: action.storage_class,
-                               age: c.age,
-                               created_before: c.created_before,
-                               is_live: c.is_live,
-                               matches_storage_class: c.matches_storage_class,
-                               num_newer_versions: c.num_newer_versions
+              new(
+                action.type,
+                storage_class: action.storage_class,
+                age: c.age,
+                created_before: c.created_before,
+                custom_time_before: c.custom_time_before,
+                days_since_custom_time: c.days_since_custom_time,
+                days_since_noncurrent_time: c.days_since_noncurrent_time,
+                is_live: c.is_live,
+                matches_storage_class: c.matches_storage_class,
+                noncurrent_time_before: c.noncurrent_time_before,
+                num_newer_versions: c.num_newer_versions
+              )
             end
 
             # @private

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.rb

@@ -355,6 +355,29 @@ 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.
+        #
+        # @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-"
@@ -389,7 +412,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
@@ -746,8 +770,9 @@ 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.
         #
         # @yield [file] a block yielding a delegate object for updating the file
         #
@@ -766,6 +791,7 @@ 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
@@ -1204,7 +1230,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,
@@ -1225,7 +1251,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,
@@ -1442,7 +1468,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
@@ -1467,10 +1493,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.
         #
@@ -1496,7 +1534,12 @@ module Google
         #   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"
@@ -1556,6 +1599,40 @@ module Google
         #   # Send the `x-goog-resumable:start` header and the content type
         #   # with the resumable upload POST request.
         #
+        # @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 = {
+        #       "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,
@@ -1565,6 +1642,7 @@ module Google
                        client_email: nil,
                        signing_key: nil,
                        private_key: nil,
+                       signer: nil,
                        query: nil,
                        scheme: "HTTPS",
                        virtual_hosted_style: nil,
@@ -1574,30 +1652,32 @@ module Google
           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,
-                              scheme: scheme,
-                              virtual_hosted_style: virtual_hosted_style,
-                              bucket_bound_hostname: bucket_bound_hostname
+            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