google-cloud-storage 1.38.0 → 1.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7377748053d6da28b196231e893002e4d80849cf558b5e983003926c19526a6c
-  data.tar.gz: b00e59073ea7230b4b654de40e6323766d6e36a562d765ad2545c8d154b16d2d
+  metadata.gz: a376f2dab9dec5118be28f8fa76c2684e0606aee749fa8387eb6672ba5fb8023
+  data.tar.gz: 1dc9bcc3f0c2cee2ee822211ea8a67f740fdd30f827715da6a8e50b98a64b21b
 SHA512:
-  metadata.gz: 65b18a6857817dd24246d287c3e51cabfb2ec61fffda26f3fc00462fd030e60c506a893ccc86a14cfc1034d882c6d488b5220e744ee2fe3316d55271c9fdaadc
-  data.tar.gz: fede3f8da08220a89dc1642fd1937cc75ea6b57ee9d210bd8a8dc4efcb5c11ff5dab0d2962c7c25f383cda4e9aa548fe8764c0ec06867abf46ca91d7fbbd33e3
+  metadata.gz: 26b8b0c1544f7e0b1d20b82e539ddaf9431caeb359b177f637f3642eccb58b089b4a9e6202b3c9f051d6c75b01b31cba4b53870b9bf3e190934c0b2d3767e302
+  data.tar.gz: 7d1b0bcfc59f1ad50831489bf2c6f1740ddae969869e221eb809be0b9107f66170f14cb9ed16d50b6d73d76621e59c6b2f5bbb8018725b2d50643fa665645177

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 1.39.0 (2022-08-24)
+
+#### Features
+
+* add support for conditional idempotent operations ([#18834](https://github.com/googleapis/google-cloud-ruby/issues/18834)) 
+
 ### 1.38.0 (2022-07-31)
 
 #### Features

data/OVERVIEW.md

@@ -563,6 +563,36 @@ require "google/cloud/storage"
 storage = Google::Cloud::Storage.new retries: 10, timeout: 120
 ```
 
+The library by default retries all API requests which are always idempotent on a
+"transient" error.
+
+For API requests which are idempotent only if the some conditions are satisfied
+(For ex. a file has the same "generation"), the library retries only if the
+condition is specified.
+
+Rather than using this default behaviour, you may choose to disable the retries
+on your own.
+
+You can pass `retries` as `0` to disable retries for all operations regardless
+of their idempotencies.
+
+```ruby
+require "google/cloud/storage"
+
+storage = Google::Cloud::Storage.new retries: 0
+```
+
+You can also disable retries for a particular operation by passing `retries` as
+`0` in the `options` field.
+
+```ruby
+require "google/cloud/storage"
+
+storage = Google::Cloud::Storage.new
+service = storage.service
+service.get_bucket bucket_name, options: {retries: 0}
+```
+
 See the [Storage status and error
 codes](https://cloud.google.com/storage/docs/json_api/v1/status-codes)
 for a list of error conditions.

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

@@ -81,11 +81,11 @@ module Google
 
         ##
         # Retrieves a list of buckets for the given project.
-        def list_buckets prefix: nil, token: nil, max: nil, user_project: nil
+        def list_buckets prefix: nil, token: nil, max: nil, user_project: nil, options: {}
           execute do
             service.list_buckets \
               @project, prefix: prefix, page_token: token, max_results: max,
-                        user_project: user_project(user_project)
+                        user_project: user_project(user_project), options: options
           end
         end
 
@@ -95,12 +95,14 @@ module Google
         def get_bucket bucket_name,
                        if_metageneration_match: nil,
                        if_metageneration_not_match: nil,
-                       user_project: nil
+                       user_project: nil,
+                       options: {}
           execute do
             service.get_bucket bucket_name,
                                if_metageneration_match: if_metageneration_match,
                                if_metageneration_not_match: if_metageneration_not_match,
-                               user_project: user_project(user_project)
+                               user_project: user_project(user_project),
+                               options: options
           end
         end
 
@@ -108,13 +110,14 @@ module Google
         # Creates a new bucket.
         # Returns Google::Apis::StorageV1::Bucket.
         def insert_bucket bucket_gapi, acl: nil, default_acl: nil,
-                          user_project: nil
+                          user_project: nil, options: {}
           execute do
             service.insert_bucket \
               @project, bucket_gapi,
               predefined_acl: acl,
               predefined_default_object_acl: default_acl,
-              user_project: user_project(user_project)
+              user_project: user_project(user_project),
+              options: options
           end
         end
 
@@ -126,11 +129,17 @@ module Google
                          predefined_default_acl: nil,
                          if_metageneration_match: nil,
                          if_metageneration_not_match: nil,
-                         user_project: nil
+                         user_project: nil,
+                         options: {}
           bucket_gapi ||= Google::Apis::StorageV1::Bucket.new
           bucket_gapi.acl = [] if predefined_acl
           bucket_gapi.default_object_acl = [] if predefined_default_acl
 
+          if options[:retry].nil?
+            is_idempotent = retry? if_metageneration_match: if_metageneration_match
+            options = is_idempotent ? {} : { retries: 0 }
+          end
+
           execute do
             service.patch_bucket bucket_name,
                                  bucket_gapi,
@@ -138,7 +147,8 @@ module Google
                                  predefined_default_object_acl: predefined_default_acl,
                                  if_metageneration_match: if_metageneration_match,
                                  if_metageneration_not_match: if_metageneration_not_match,
-                                 user_project: user_project(user_project)
+                                 user_project: user_project(user_project),
+                                 options: options
           end
         end
 
@@ -147,119 +157,132 @@ module Google
         def delete_bucket bucket_name,
                           if_metageneration_match: nil,
                           if_metageneration_not_match: nil,
-                          user_project: nil
+                          user_project: nil,
+                          options: {}
           execute do
             service.delete_bucket bucket_name,
                                   if_metageneration_match: if_metageneration_match,
                                   if_metageneration_not_match: if_metageneration_not_match,
-                                  user_project: user_project(user_project)
+                                  user_project: user_project(user_project),
+                                  options: options
           end
         end
 
         ##
         # Locks retention policy on a bucket.
         def lock_bucket_retention_policy bucket_name, metageneration,
-                                         user_project: nil
+                                         user_project: nil,
+                                         options: {}
           execute do
             service.lock_bucket_retention_policy \
               bucket_name, metageneration,
-              user_project: user_project(user_project)
+              user_project: user_project(user_project),
+              options: options
           end
         end
 
         ##
         # Retrieves a list of ACLs for the given bucket.
-        def list_bucket_acls bucket_name, user_project: nil
+        def list_bucket_acls bucket_name, user_project: nil, options: {}
           execute do
             service.list_bucket_access_controls \
-              bucket_name, user_project: user_project(user_project)
+              bucket_name, user_project: user_project(user_project),
+              options: options
           end
         end
 
         ##
         # Creates a new bucket ACL.
-        def insert_bucket_acl bucket_name, entity, role, user_project: nil
+        def insert_bucket_acl bucket_name, entity, role, user_project: nil, options: {}
           params = { entity: entity, role: role }.delete_if { |_k, v| v.nil? }
           new_acl = Google::Apis::StorageV1::BucketAccessControl.new(**params)
           execute do
             service.insert_bucket_access_control \
-              bucket_name, new_acl, user_project: user_project(user_project)
+              bucket_name, new_acl, user_project: user_project(user_project),
+              options: options
           end
         end
 
         ##
         # Permanently deletes a bucket ACL.
-        def delete_bucket_acl bucket_name, entity, user_project: nil
+        def delete_bucket_acl bucket_name, entity, user_project: nil, options: {}
           execute do
             service.delete_bucket_access_control \
-              bucket_name, entity, user_project: user_project(user_project)
+              bucket_name, entity, user_project: user_project(user_project),
+              options: options
           end
         end
 
         ##
         # Retrieves a list of default ACLs for the given bucket.
-        def list_default_acls bucket_name, user_project: nil
+        def list_default_acls bucket_name, user_project: nil, options: {}
           execute do
             service.list_default_object_access_controls \
-              bucket_name, user_project: user_project(user_project)
+              bucket_name, user_project: user_project(user_project),
+              options: options
           end
         end
 
         ##
         # Creates a new default ACL.
-        def insert_default_acl bucket_name, entity, role, user_project: nil
+        def insert_default_acl bucket_name, entity, role, user_project: nil, options: {}
           param = { entity: entity, role: role }.delete_if { |_k, v| v.nil? }
           new_acl = Google::Apis::StorageV1::ObjectAccessControl.new(**param)
           execute do
             service.insert_default_object_access_control \
-              bucket_name, new_acl, user_project: user_project(user_project)
+              bucket_name, new_acl, user_project: user_project(user_project),
+              options: options
           end
         end
 
         ##
         # Permanently deletes a default ACL.
-        def delete_default_acl bucket_name, entity, user_project: nil
+        def delete_default_acl bucket_name, entity, user_project: nil, options: {}
           execute do
             service.delete_default_object_access_control \
-              bucket_name, entity, user_project: user_project(user_project)
+              bucket_name, entity, user_project: user_project(user_project),
+              options: options
           end
         end
 
         ##
         # Returns Google::Apis::StorageV1::Policy
-        def get_bucket_policy bucket_name, requested_policy_version: nil, user_project: nil
+        def get_bucket_policy bucket_name, requested_policy_version: nil, user_project: nil,
+                              options: {}
           # get_bucket_iam_policy(bucket, fields: nil, quota_user: nil,
           #                               user_ip: nil, options: nil)
           execute do
             service.get_bucket_iam_policy bucket_name, options_requested_policy_version: requested_policy_version,
-                                                       user_project: user_project(user_project)
+                                                       user_project: user_project(user_project), options: options
           end
         end
 
         ##
         # Returns Google::Apis::StorageV1::Policy
-        def set_bucket_policy bucket_name, new_policy, user_project: nil
+        def set_bucket_policy bucket_name, new_policy, user_project: nil, options: {}
           execute do
             service.set_bucket_iam_policy \
-              bucket_name, new_policy, user_project: user_project(user_project)
+              bucket_name, new_policy, user_project: user_project(user_project), options: options
           end
         end
 
         ##
         # Returns Google::Apis::StorageV1::TestIamPermissionsResponse
-        def test_bucket_permissions bucket_name, permissions, user_project: nil
+        def test_bucket_permissions bucket_name, permissions, user_project: nil, options: {}
           execute do
             service.test_bucket_iam_permissions \
-              bucket_name, permissions, user_project: user_project(user_project)
+              bucket_name, permissions, user_project: user_project(user_project),
+              options: options
           end
         end
 
         ##
         # Retrieves a list of Pub/Sub notification subscriptions for a bucket.
-        def list_notifications bucket_name, user_project: nil
+        def list_notifications bucket_name, user_project: nil, options: {}
           execute do
             service.list_notifications bucket_name,
-                                       user_project: user_project(user_project)
+                                       user_project: user_project(user_project),
+                                       options: options
           end
         end
 
@@ -267,7 +290,7 @@ module Google
         # Creates a new Pub/Sub notification subscription for a bucket.
         def insert_notification bucket_name, topic_name, custom_attrs: nil,
                                 event_types: nil, prefix: nil, payload: nil,
-                                user_project: nil
+                                user_project: nil, options: {}
           params =
             { custom_attributes: custom_attrs,
               event_types: event_types(event_types),
@@ -279,38 +302,43 @@ module Google
           execute do
             service.insert_notification \
               bucket_name, new_notification,
-              user_project: user_project(user_project)
+              user_project: user_project(user_project),
+              options: options
           end
         end
 
         ##
         # Retrieves a Pub/Sub notification subscription for a bucket.
-        def get_notification bucket_name, notification_id, user_project: nil
+        def get_notification bucket_name, notification_id, user_project: nil, options: {}
           execute do
             service.get_notification bucket_name, notification_id,
-                                     user_project: user_project(user_project)
+                                     user_project: user_project(user_project),
+                                     options: options
           end
         end
 
         ##
         # Deletes a new Pub/Sub notification subscription for a bucket.
-        def delete_notification bucket_name, notification_id, user_project: nil
+        def delete_notification bucket_name, notification_id, user_project: nil, options: {}
           execute do
             service.delete_notification bucket_name, notification_id,
-                                        user_project: user_project(user_project)
+                                        user_project: user_project(user_project),
+                                        options: options
           end
         end
 
         ##
         # Retrieves a list of files matching the criteria.
         def list_files bucket_name, delimiter: nil, max: nil, token: nil,
-                       prefix: nil, versions: nil, user_project: nil
+                       prefix: nil, versions: nil, user_project: nil,
+                       options: {}
           execute do
             service.list_objects \
               bucket_name, delimiter: delimiter, max_results: max,
                            page_token: token, prefix: prefix,
                            versions: versions,
-                           user_project: user_project(user_project)
+                           user_project: user_project(user_project),
+                           options: options
           end
         end
 
@@ -338,7 +366,8 @@ module Google
                         if_generation_not_match: nil,
                         if_metageneration_match: nil,
                         if_metageneration_not_match: nil,
-                        user_project: nil
+                        user_project: nil,
+                        options: {}
           params = {
             cache_control: cache_control,
             content_type: content_type,
@@ -356,6 +385,13 @@ module Google
           file_obj = Google::Apis::StorageV1::Object.new(**params)
           content_type ||= mime_type_for(path || Pathname(source).to_path)
 
+          if options[:retry].nil?
+            is_idempotent = retry? if_generation_match: if_generation_match
+            options = is_idempotent ? key_options(key) : key_options(key).merge(retries: 0)
+          else
+            options = key_options(key).merge options
+          end
+
           execute do
             service.insert_object bucket_name,
                                   file_obj,
@@ -370,7 +406,7 @@ module Google
                                   if_metageneration_not_match: if_metageneration_not_match,
                                   kms_key_name: kms_key,
                                   user_project: user_project(user_project),
-                                  options: key_options(key)
+                                  options: options
           end
         end
 
@@ -384,7 +420,8 @@ module Google
                      if_metageneration_match: nil,
                      if_metageneration_not_match: nil,
                      key: nil,
-                     user_project: nil
+                     user_project: nil,
+                     options: {}
           execute do
             service.get_object \
               bucket_name, file_path,
@@ -394,7 +431,7 @@ module Google
               if_metageneration_match: if_metageneration_match,
               if_metageneration_not_match: if_metageneration_not_match,
               user_project: user_project(user_project),
-              options: key_options(key)
+              options: key_options(key).merge(options)
           end
         end
 
@@ -419,8 +456,17 @@ module Google
                          if_source_metageneration_match: nil,
                          if_source_metageneration_not_match: nil,
                          token: nil,
-                         user_project: nil
+                         user_project: nil,
+                         options: {}
           key_options = rewrite_key_options source_key, destination_key
+
+          if options[:retry].nil?
+            is_idempotent = retry? if_generation_match: if_generation_match
+            options = is_idempotent ? key_options : key_options.merge(retries: 0)
+          else
+            options = key_options.merge options
+          end
+
           execute do
             service.rewrite_object source_bucket_name,
                                    source_file_path,
@@ -440,7 +486,7 @@ module Google
                                    if_source_metageneration_not_match: if_source_metageneration_not_match,
                                    rewrite_token: token,
                                    user_project: user_project(user_project),
-                                   options: key_options
+                                   options: options
           end
         end
 
@@ -455,12 +501,20 @@ module Google
                          if_source_generation_match: nil,
                          if_generation_match: nil,
                          if_metageneration_match: nil,
-                         user_project: nil
+                         user_project: nil,
+                         options: {}
 
           source_objects = compose_file_source_objects source_files, if_source_generation_match
           compose_req = Google::Apis::StorageV1::ComposeRequest.new source_objects: source_objects,
                                                                     destination: destination_gapi
 
+          if options[:retry].nil?
+            is_idempotent = retry? if_generation_match: if_generation_match
+            options = is_idempotent ? key_options(key) : key_options(key).merge(retries: 0)
+          else
+            options = key_options.merge options
+          end
+
           execute do
             service.compose_object bucket_name,
                                    destination_path,
@@ -469,7 +523,7 @@ module Google
                                    if_generation_match: if_generation_match,
                                    if_metageneration_match: if_metageneration_match,
                                    user_project: user_project(user_project),
-                                   options: key_options(key)
+                                   options: options
           end
         end
 
@@ -483,8 +537,8 @@ module Google
         #     Apis::StorageV1::StorageService and Apis::Core::DownloadCommand at
         #     the end of this file.
         def download_file bucket_name, file_path, target_path, generation: nil,
-                          key: nil, range: nil, user_project: nil
-          options = key_options key
+                          key: nil, range: nil, user_project: nil, options: {}
+          options = key_options(key).merge(options)
           options = range_header options, range
 
           execute do
@@ -507,8 +561,15 @@ module Google
                        if_metageneration_match: nil,
                        if_metageneration_not_match: nil,
                        predefined_acl: nil,
-                       user_project: nil
+                       user_project: nil,
+                       options: {}
           file_gapi ||= Google::Apis::StorageV1::Object.new
+
+          if options[:retry].nil?
+            is_idempotent = retry? if_metageneration_match: if_metageneration_match
+            options = is_idempotent ? {} : { retries: 0 }
+          end
+
           execute do
             service.patch_object bucket_name,
                                  file_path,
@@ -519,7 +580,8 @@ module Google
                                  if_metageneration_match: if_metageneration_match,
                                  if_metageneration_not_match: if_metageneration_not_match,
                                  predefined_acl: predefined_acl,
-                                 user_project: user_project(user_project)
+                                 user_project: user_project(user_project),
+                                 options: options
           end
         end
 
@@ -532,7 +594,14 @@ module Google
                         if_generation_not_match: nil,
                         if_metageneration_match: nil,
                         if_metageneration_not_match: nil,
-                        user_project: nil
+                        user_project: nil,
+                        options: {}
+
+          if options[:retry].nil?
+            is_idempotent = retry? generation: generation, if_generation_match: if_generation_match
+            options = is_idempotent ? {} : { retries: 0 }
+          end
+
           execute do
             service.delete_object bucket_name, file_path,
                                   generation: generation,
@@ -540,40 +609,45 @@ module Google
                                   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(user_project)
+                                  user_project: user_project(user_project),
+                                  options: options
           end
         end
 
         ##
         # Retrieves a list of ACLs for the given file.
-        def list_file_acls bucket_name, file_name, user_project: nil
+        def list_file_acls bucket_name, file_name, user_project: nil, options: {}
           execute do
             service.list_object_access_controls \
-              bucket_name, file_name, user_project: user_project(user_project)
+              bucket_name, file_name, user_project: user_project(user_project),
+              options: options
           end
         end
 
         ##
         # Creates a new file ACL.
         def insert_file_acl bucket_name, file_name, entity, role,
-                            generation: nil, user_project: nil
+                            generation: nil, user_project: nil,
+                            options: {}
           params = { entity: entity, role: role }.delete_if { |_k, v| v.nil? }
           new_acl = Google::Apis::StorageV1::ObjectAccessControl.new(**params)
           execute do
             service.insert_object_access_control \
               bucket_name, file_name, new_acl,
-              generation: generation, user_project: user_project(user_project)
+              generation: generation, user_project: user_project(user_project),
+              options: options
           end
         end
 
         ##
         # Permanently deletes a file ACL.
         def delete_file_acl bucket_name, file_name, entity, generation: nil,
-                            user_project: nil
+                            user_project: nil, options: {}
           execute do
             service.delete_object_access_control \
               bucket_name, file_name, entity,
-              generation: generation, user_project: user_project(user_project)
+              generation: generation, user_project: user_project(user_project),
+              options: options
           end
         end
 
@@ -581,32 +655,37 @@ module Google
         # Creates a new HMAC key for the specified service account.
         # Returns Google::Apis::StorageV1::HmacKey.
         def create_hmac_key service_account_email, project_id: nil,
-                            user_project: nil
+                            user_project: nil, options: {}
           execute do
             service.create_project_hmac_key \
               (project_id || @project), service_account_email,
-              user_project: user_project(user_project)
+              user_project: user_project(user_project),
+              options: options
           end
         end
 
         ##
         # Deletes an HMAC key. Key must be in the INACTIVE state.
-        def delete_hmac_key access_id, project_id: nil, user_project: nil
+        def delete_hmac_key access_id, project_id: nil, user_project: nil,
+                            options: {}
           execute do
             service.delete_project_hmac_key \
               (project_id || @project), access_id,
-              user_project: user_project(user_project)
+              user_project: user_project(user_project),
+              options: options
           end
         end
 
         ##
         # Retrieves an HMAC key's metadata.
         # Returns Google::Apis::StorageV1::HmacKeyMetadata.
-        def get_hmac_key access_id, project_id: nil, user_project: nil
+        def get_hmac_key access_id, project_id: nil, user_project: nil,
+                         options: {}
           execute do
             service.get_project_hmac_key \
               (project_id || @project), access_id,
-              user_project: user_project(user_project)
+              user_project: user_project(user_project),
+              options: options
           end
         end
 
@@ -615,14 +694,15 @@ module Google
         # Returns Google::Apis::StorageV1::HmacKeysMetadata.
         def list_hmac_keys max: nil, token: nil, service_account_email: nil,
                            project_id: nil, show_deleted_keys: nil,
-                           user_project: nil
+                           user_project: nil, options: {}
           execute do
             service.list_project_hmac_keys \
               (project_id || @project),
               max_results: max, page_token: token,
               service_account_email: service_account_email,
               show_deleted_keys: show_deleted_keys,
-              user_project: user_project(user_project)
+              user_project: user_project(user_project),
+              options: options
           end
         end
 
@@ -631,11 +711,13 @@ module Google
         # for valid states.
         # Returns Google::Apis::StorageV1::HmacKeyMetadata.
         def update_hmac_key access_id, hmac_key_metadata_object,
-                            project_id: nil, user_project: nil
+                            project_id: nil, user_project: nil,
+                            options: {}
           execute do
             service.update_project_hmac_key \
               (project_id || @project), access_id, hmac_key_metadata_object,
-              user_project: user_project(user_project)
+              user_project: user_project(user_project),
+              options: options
           end
         end
 
@@ -771,6 +853,10 @@ module Google
         rescue Google::Apis::Error => e
           raise Google::Cloud::Error.from_error(e)
         end
+
+        def retry? query_params
+          query_params.any? { |_key, val| !val.nil? }
+        end
       end
     end
   end

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Storage
-      VERSION = "1.38.0".freeze
+      VERSION = "1.39.0".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-storage
 version: !ruby/object:Gem::Version
-  version: 1.38.0
+  version: 1.39.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-08-01 00:00:00.000000000 Z
+date: 2022-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core