google-cloud-pubsub 2.10.0 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfea48d152ed64a8f424def3c0ecdbdc7458da875f12d9ca72aa04a61a682c8c
-  data.tar.gz: b19ac0708ab621f94c90e76fa9819ebd06ef4c4d4afd158b5da185dea5cfbb65
+  metadata.gz: 2c1517a2425dde72d0dc828b7a9547377b2c77d040ab456e75a22da05ec435a9
+  data.tar.gz: 8d5dcddd9253520df1192021cd9cdf6b582045aa39b32a4213870ed95a6a81db
 SHA512:
-  metadata.gz: ccb470b1228bbb234000c74f05396cbfcfe89780557962d4fa5268ad32a164627a48d0a45f605c6cbccdae2944cdf6f6829cb6310c73a0b0fc9de32495a565f4
-  data.tar.gz: 4dbce7523618c04e64ba84231bc9cfce06b9c16026a18c51c451337a7db851c122e47f0e1cc3d07a841ec4fcdd67a1b6ee338c888721b3e77db3b18a9f34948b
+  metadata.gz: 23fe9089e74ffb8f578c9cf3f7122601f3e3440c3d891b80231fc0fd20c7f11128f7c6402f5be9b1e8737ddd6c18f7a1756c2ecdeae3771653506603cab25cef
+  data.tar.gz: c874cdff8afc7f4aeef73ee7c48b556314c2698934f63349644fe9c9e58b00dfdbb45b96c8fd58fad8218af1225c551ce72db98ee26744bc86eec9df3a267747

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Release History
 
+### 2.11.0 (2022-08-01)
+
+#### Features
+
+* create exactly once delivery enabled subscription ([#18824](https://github.com/googleapis/google-cloud-ruby/issues/18824)) 
+* Let user register callback and get acknowledgement result ([#18702](https://github.com/googleapis/google-cloud-ruby/issues/18702)) 
+* retry transient failures in ack/modack in timed unary buffer ([#18395](https://github.com/googleapis/google-cloud-ruby/issues/18395)) 
+
 ### 2.10.0 (2022-06-14)
 
 #### Features

data/lib/google/cloud/pubsub/acknowledge_result.rb

@@ -0,0 +1,79 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module PubSub
+      ##
+      # The result of a ack/nack/modack on messages.
+      #
+      # When the operation was successful the result will be marked
+      # {#succeeded?}. Otherwise, the result will be marked {#failed?} and the
+      # error raised will be availabe on {#error}.
+      #
+      class AcknowledgeResult
+        ##
+        # The constants below represents the status of ack/modack operations.
+        # Indicates successful ack/modack
+        SUCCESS = 1
+
+        ##
+        # Indicates occurence of permenant permission denied error
+        PERMISSION_DENIED = 2
+
+        ##
+        # Indicates occurence of permenant failed precondition error
+        FAILED_PRECONDITION = 3
+
+        ##
+        # Indicates occurence of permenant permission denied error
+        INVALID_ACK_ID = 4
+
+        ##
+        # Indicates occurence of permenant uncatogorised error
+        OTHER = 5
+
+        ##
+        # @return [Google::Cloud::Error] Error object of ack/modack operation
+        attr_reader :error
+
+        ##
+        # @return [Numeric] Status of the ack/modack operation.
+        attr_reader :status
+
+        ##
+        # @private Create an PublishResult object.
+        def initialize status, error = nil
+          @error = error
+          @status = status
+        end
+
+        ##
+        # @return [Boolean] Whether the operation was successful.
+        def succeeded?
+          @status == SUCCESS
+        end
+
+        ##
+        # @return [Boolean] Whether the operation failed.
+        def failed?
+          !succeeded?
+        end
+      end
+    end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
+  end
+end

data/lib/google/cloud/pubsub/received_message.rb

@@ -161,6 +161,29 @@ module Google
         ##
         # Acknowledges receipt of the message.
         #
+        # @yield [callback] The block to be called when reject operation is done.
+        # @yieldparam [Google::Cloud::PubSub::AcknowledgeResult] Result object that contains the status and error.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   subscriber = sub.listen do |received_message|
+        #     puts received_message.message.data
+        #
+        #     received_message.acknowledge! do |result|
+        #       puts result.status
+        #     end
+        #   end
+        #
+        #   # Start background threads that will call block passed to listen.
+        #   subscriber.start
+        #
+        #   # Shut down the subscriber when ready to stop receiving messages.
+        #   subscriber.stop!
+        #
         # @example
         #   require "google/cloud/pubsub"
         #
@@ -179,9 +202,9 @@ module Google
         #   # Shut down the subscriber when ready to stop receiving messages.
         #   subscriber.stop!
         #
-        def acknowledge!
+        def acknowledge! &block
           ensure_subscription!
-          subscription.acknowledge ack_id
+          subscription.acknowledge ack_id, &block
         end
         alias ack! acknowledge!
 
@@ -197,6 +220,30 @@ module Google
         #   seconds after the call is made. Specifying `0` may immediately make
         #   the message available for another pull request.
         #
+        # @yield [callback] The block to be called when reject operation is done.
+        # @yieldparam [Google::Cloud::PubSub::AcknowledgeResult] Result object that contains the status and error.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   subscriber = sub.listen do |received_message|
+        #     puts received_message.message.data
+        #
+        #     # Delay for 2 minutes
+        #     received_message.modify_ack_deadline! 120 do |result|
+        #       puts result.status
+        #     end
+        #   end
+        #
+        #   # Start background threads that will call block passed to listen.
+        #   subscriber.start
+        #
+        #   # Shut down the subscriber when ready to stop receiving messages.
+        #   subscriber.stop!
+        #
         # @example
         #   require "google/cloud/pubsub"
         #
@@ -216,9 +263,9 @@ module Google
         #   # Shut down the subscriber when ready to stop receiving messages.
         #   subscriber.stop!
         #
-        def modify_ack_deadline! new_deadline
+        def modify_ack_deadline! new_deadline, &block
           ensure_subscription!
-          subscription.modify_ack_deadline new_deadline, ack_id
+          subscription.modify_ack_deadline new_deadline, ack_id, &block
         end
 
         ##
@@ -227,6 +274,30 @@ module Google
         #
         # This will make the message available for redelivery.
         #
+        # @yield [callback] The block to be called when reject operation is done.
+        # @yieldparam [Google::Cloud::PubSub::AcknowledgeResult] Result object that contains the status and error.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   subscriber = sub.listen do |received_message|
+        #     puts received_message.message.data
+        #
+        #     # Release message back to the API.
+        #     received_message.reject! do |result|
+        #       puts result.status
+        #     end
+        #   end
+        #
+        #   # Start background threads that will call block passed to listen.
+        #   subscriber.start
+        #
+        #   # Shut down the subscriber when ready to stop receiving messages.
+        #   subscriber.stop!
+        #
         # @example
         #   require "google/cloud/pubsub"
         #
@@ -246,8 +317,8 @@ module Google
         #   # Shut down the subscriber when ready to stop receiving messages.
         #   subscriber.stop!
         #
-        def reject!
-          modify_ack_deadline! 0
+        def reject! &block
+          modify_ack_deadline! 0, &block
         end
         alias nack! reject!
         alias ignore! reject!

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

@@ -204,18 +204,8 @@ module Google
         ##
         # Creates a subscription on a given topic for a given subscriber.
         def create_subscription topic, subscription_name, options = {}
-          subscriber.create_subscription \
-            name:                       subscription_path(subscription_name, options),
-            topic:                      topic_path(topic),
-            push_config:                options[:push_config],
-            ack_deadline_seconds:       options[:deadline],
-            retain_acked_messages:      options[:retain_acked],
-            message_retention_duration: Convert.number_to_duration(options[:retention]),
-            labels:                     options[:labels],
-            enable_message_ordering:    options[:message_ordering],
-            filter:                     options[:filter],
-            dead_letter_policy:         dead_letter_policy(options),
-            retry_policy:               options[:retry_policy]
+          updated_option = construct_create_subscription_options topic, subscription_name, options
+          subscriber.create_subscription(**updated_option)
         end
 
         def update_subscription subscription_obj, *fields
@@ -255,11 +245,7 @@ module Google
         ##
         # Acknowledges receipt of a message.
         def acknowledge subscription, *ack_ids
-          begin
-            subscriber.acknowledge subscription: subscription_path(subscription), ack_ids: ack_ids
-          rescue StandardError => e
-            raise e unless e.cause.is_a? GRPC::BadStatus
-          end
+          subscriber.acknowledge subscription: subscription_path(subscription), ack_ids: ack_ids
         end
 
         ##
@@ -279,13 +265,9 @@ module Google
         ##
         # Modifies the ack deadline for a specific message.
         def modify_ack_deadline subscription, ids, deadline
-          begin
-            subscriber.modify_ack_deadline subscription:         subscription_path(subscription),
-                                           ack_ids:              Array(ids),
-                                           ack_deadline_seconds: deadline
-          rescue StandardError => e
-            raise e unless e.cause.is_a? GRPC::BadStatus
-          end
+          subscriber.modify_ack_deadline subscription:         subscription_path(subscription),
+                                         ack_ids:              Array(ids),
+                                         ack_deadline_seconds: deadline
         end
 
         ##
@@ -496,6 +478,30 @@ module Google
           end
           policy
         end
+
+        private
+
+        def construct_create_subscription_options topic, subscription_name, options
+          excess_options = [:deadline,
+                            :retention,
+                            :retain_acked,
+                            :message_ordering,
+                            :endpoint,
+                            :dead_letter_topic_name,
+                            :dead_letter_max_delivery_attempts,
+                            :dead_letter_topic]
+
+          new_options = options.filter { |k, v| !v.nil? && !excess_options.include?(k) }
+          new_options[:name] = subscription_path subscription_name, options
+          new_options[:topic] = topic_path topic
+          new_options[:message_retention_duration] = Convert.number_to_duration options[:retention]
+          new_options[:dead_letter_policy] = dead_letter_policy options
+          new_options[:ack_deadline_seconds] = options[:deadline]
+          new_options[:retain_acked_messages] = options[:retain_acked]
+          new_options[:enable_message_ordering] = options[:message_ordering]
+
+          new_options.compact
+        end
       end
     end
 

data/lib/google/cloud/pubsub/subscriber/stream.rb

@@ -134,13 +134,13 @@ module Google
 
           ##
           # @private
-          def acknowledge *messages
+          def acknowledge *messages, &callback
             ack_ids = coerce_ack_ids messages
             return true if ack_ids.empty?
 
             synchronize do
               @inventory.remove ack_ids
-              @subscriber.buffer.acknowledge ack_ids
+              @subscriber.buffer.acknowledge ack_ids, callback
             end
 
             true
@@ -148,13 +148,13 @@ module Google
 
           ##
           # @private
-          def modify_ack_deadline deadline, *messages
+          def modify_ack_deadline deadline, *messages, &callback
             mod_ack_ids = coerce_ack_ids messages
             return true if mod_ack_ids.empty?
 
             synchronize do
               @inventory.remove mod_ack_ids
-              @subscriber.buffer.modify_ack_deadline deadline, mod_ack_ids
+              @subscriber.buffer.modify_ack_deadline deadline, mod_ack_ids, callback
             end
 
             true
@@ -253,6 +253,7 @@ module Google
                 synchronize do
                   update_min_duration_per_lease_extension new_exactly_once_delivery_enabled
                   @exactly_once_delivery_enabled = new_exactly_once_delivery_enabled unless new_exactly_once_delivery_enabled.nil? 
+                  @subscriber.exactly_once_delivery_enabled = @exactly_once_delivery_enabled
 
                   # Create receipt of received messages reception
                   @subscriber.buffer.modify_ack_deadline @subscriber.deadline, response.received_messages.map(&:ack_id)

data/lib/google/cloud/pubsub/subscriber/timed_unary_buffer.rb

@@ -14,7 +14,10 @@
 
 
 require "concurrent"
+require "google/cloud/errors"
+require "google/cloud/pubsub/acknowledge_result"
 require "monitor"
+require "retriable"
 
 module Google
   module Cloud
@@ -27,6 +30,21 @@ module Google
 
           attr_reader :max_bytes
           attr_reader :interval
+          attr_reader :retry_thread_pool
+          attr_reader :callback_thread_pool
+
+          PERMANENT_FAILURE = "PERMANENT_FAILURE".freeze
+          # Google::Cloud::Unavailable error is already retried at gapic level
+          RETRIABLE_ERRORS = [Google::Cloud::CanceledError,
+                              Google::Cloud::DeadlineExceededError,
+                              Google::Cloud::InternalError,
+                              Google::Cloud::ResourceExhaustedError,
+                              Google::Cloud::InvalidArgumentError].freeze
+          MAX_RETRY_DURATION = 600 # 600s since the server allows ack/modacks for 10 mins max
+          MAX_TRIES = 15
+          BASE_INTERVAL = 1
+          MAX_INTERVAL = 64
+          MULTIPLIER = 2
 
           def initialize subscriber, max_bytes: 500_000, interval: 1.0
             super() # to init MonitorMixin
@@ -40,30 +58,37 @@ module Google
             # entry.
             @register = {}
 
+            @ack_callback_register = {}
+            @modack_callback_register = {}
+
+            @retry_thread_pool = Concurrent::ThreadPoolExecutor.new max_threads: @subscriber.callback_threads
+            @callback_thread_pool = Concurrent::ThreadPoolExecutor.new max_threads: @subscriber.callback_threads
             @task = Concurrent::TimerTask.new execution_interval: interval do
               flush!
             end
           end
 
-          def acknowledge ack_ids
+          def acknowledge ack_ids, callback = nil
             return if ack_ids.empty?
 
             synchronize do
               ack_ids.each do |ack_id|
                 # ack has no deadline set, use :ack indicate it is an ack
                 @register[ack_id] = :ack
+                @ack_callback_register[ack_id] = callback unless callback.nil?
               end
             end
 
             true
           end
 
-          def modify_ack_deadline deadline, ack_ids
+          def modify_ack_deadline deadline, ack_ids, callback = nil
             return if ack_ids.empty?
 
             synchronize do
               ack_ids.each do |ack_id|
                 @register[ack_id] = deadline
+                @modack_callback_register[ack_id] = callback unless callback.nil?
               end
             end
 
@@ -90,20 +115,46 @@ module Google
 
             # Perform the RCP calls concurrently
             with_threadpool do |pool|
-              requests[:acknowledge].each do |ack_req|
-                add_future pool do
+              make_acknowledge_request requests, pool
+              make_modack_request requests, pool
+            end
+
+            true
+          end
+
+          def make_acknowledge_request requests, pool
+            requests[:acknowledge].each do |ack_req|
+              add_future pool do
+                begin
                   @subscriber.service.acknowledge ack_req.subscription, *ack_req.ack_ids
+                  handle_callback AcknowledgeResult.new(AcknowledgeResult::SUCCESS), ack_req.ack_ids
+                rescue *RETRIABLE_ERRORS => e
+                  handle_failure e, ack_req.ack_ids if @subscriber.exactly_once_delivery_enabled
+                rescue StandardError => e
+                  handle_callback construct_result(e), ack_req.ack_ids
                 end
               end
-              requests[:modify_ack_deadline].each do |mod_ack_req|
-                add_future pool do
+            end
+          end
+
+          def make_modack_request requests, pool
+            requests[:modify_ack_deadline].each do |mod_ack_req|
+              add_future pool do
+                begin
                   @subscriber.service.modify_ack_deadline mod_ack_req.subscription, mod_ack_req.ack_ids,
                                                           mod_ack_req.ack_deadline_seconds
+                  handle_callback AcknowledgeResult.new(AcknowledgeResult::SUCCESS),
+                                  mod_ack_req.ack_ids,
+                                  modack: true
+                rescue *RETRIABLE_ERRORS => e
+                  if @subscriber.exactly_once_delivery_enabled
+                    handle_failure e, mod_ack_req.ack_ids, mod_ack_req.ack_deadline_seconds
+                  end
+                rescue StandardError => e
+                  handle_callback construct_result(e), mod_ack_req.ack_ids, modack: true
                 end
               end
             end
-
-            true
           end
 
           def start
@@ -114,8 +165,9 @@ module Google
 
           def stop
             @task.shutdown
+            @retry_thread_pool.shutdown
+            @callback_thread_pool.shutdown
             flush!
-
             self
           end
 
@@ -129,6 +181,121 @@ module Google
 
           private
 
+          def handle_failure error, ack_ids, ack_deadline_seconds = nil
+            error_ack_ids = parse_error error, modack: ack_deadline_seconds.nil?
+            unless error_ack_ids.nil?
+              handle_callback AcknowledgeResult.new(AcknowledgeResult::SUCCESS),
+                              ack_ids - error_ack_ids,
+                              modack: ack_deadline_seconds.nil?
+              ack_ids = error_ack_ids
+            end
+            perform_retry_async ack_ids, ack_deadline_seconds
+          end
+
+          def parse_error error, modack: false
+            metadata = error.error_metadata
+            return if metadata.nil?
+            permanent_failures, temporary_failures = metadata.partition do |_, v|
+              v.include? PERMANENT_FAILURE
+            end.map(&:to_h)
+            unless permanent_failures.empty?
+              handle_callback construct_result(error),
+                              permanent_failures.keys.map(&:to_s),
+                              modack: modack
+            end
+            temporary_failures.keys.map(&:to_s) unless temporary_failures.empty?
+          end
+
+          def construct_result error
+            case error
+            when Google::Cloud::PermissionDeniedError
+              AcknowledgeResult.new AcknowledgeResult::PERMISSION_DENIED, error
+            when Google::Cloud::FailedPreconditionError
+              AcknowledgeResult.new AcknowledgeResult::FAILED_PRECONDITION, error
+            when Google::Cloud::InvalidArgumentError
+              AcknowledgeResult.new AcknowledgeResult::INVALID_ACK_ID, error
+            else
+              AcknowledgeResult.new AcknowledgeResult::OTHER, error
+            end
+          end
+
+          def handle_callback result, ack_ids, modack: false
+            ack_ids.each do |ack_id|
+              callback = modack ? @modack_callback_register[ack_id] : @ack_callback_register[ack_id]
+              perform_callback_async result, callback unless callback.nil?
+            end
+            synchronize do
+              if modack
+                @modack_callback_register.delete_if { |ack_id, _| ack_ids.include? ack_id }
+              else
+                @ack_callback_register.delete_if { |ack_id, _| ack_ids.include? ack_id }
+              end
+            end
+          end
+
+          def perform_callback_async result, callback
+            return unless retry_thread_pool.running?
+            Concurrent::Promises.future_on(
+              callback_thread_pool, result, callback, &method(:perform_callback_sync)
+            )
+          end
+
+          def perform_callback_sync result, callback
+            begin
+              callback.call result unless stopped?
+            rescue StandardError => e
+              @subscriber.error! e
+            end
+          end
+
+          def perform_retry_async ack_ids, ack_deadline_seconds = nil
+            return unless retry_thread_pool.running?
+            Concurrent::Promises.future_on(
+              retry_thread_pool, ack_ids, ack_deadline_seconds, &method(:retry_transient_error)
+            )
+          end
+
+          def retry_transient_error ack_ids, ack_deadline_seconds
+            if ack_deadline_seconds.nil?
+              retry_request ack_ids, ack_deadline_seconds.nil? do |retry_ack_ids|
+                @subscriber.service.acknowledge subscription_name, *retry_ack_ids
+                handle_callback AcknowledgeResult.new AcknowledgeResult::SUCCESS, retry_ack_ids
+              end
+            else
+              retry_request ack_ids, ack_deadline_seconds.nil? do |retry_ack_ids|
+                @subscriber.service.modify_ack_deadline subscription_name, retry_ack_ids, ack_deadline_seconds
+                handle_callback AcknowledgeResult.new AcknowledgeResult::SUCCESS, retry_ack_ids, modack: true
+              end
+            end
+          end
+
+          def retry_request ack_ids, modack
+            begin
+              Retriable.retriable tries: MAX_TRIES,
+                                  base_interval: BASE_INTERVAL,
+                                  max_interval: MAX_INTERVAL,
+                                  multiplier: MULTIPLIER,
+                                  max_elapsed_time: MAX_RETRY_DURATION,
+                                  on: RETRIABLE_ERRORS do
+                return if ack_ids.nil?
+                begin
+                  yield ack_ids
+                rescue Google::Cloud::InvalidArgumentError => e
+                  error_ack_ids = parse_error e.error_metadata, modack: modack
+                  unless error_ack_ids.nil?
+                    handle_callback AcknowledgeResult.new(AcknowledgeResult::SUCCESS),
+                                    ack_ids - error_ack_ids,
+                                    modack: modack
+                  end
+                  ack_ids = error_ack_ids
+                  raise e
+                end
+              end
+            rescue StandardError => e
+              handle_callback e, ack_ids, modack: modack
+            end
+          end
+
           def flush_requests!
             prev_reg =
               synchronize do

data/lib/google/cloud/pubsub/subscriber.rb

@@ -76,6 +76,10 @@ module Google
         # @private Implementation attributes.
         attr_reader :stream_pool, :thread_pool, :buffer, :service
 
+        ##
+        # @private Implementation attributes.
+        attr_accessor :exactly_once_delivery_enabled
+
         ##
         # @private Create an empty {Subscriber} object.
         def initialize subscription_name, callback, deadline: nil, message_ordering: nil, streams: nil, inventory: nil,
@@ -91,6 +95,7 @@ module Google
           @message_ordering = message_ordering
           @callback_threads = Integer(threads[:callback] || 8)
           @push_threads = Integer(threads[:push] || 4)
+          @exactly_once_delivery_enabled = nil
 
           @service = service
 

data/lib/google/cloud/pubsub/topic.rb

@@ -364,7 +364,7 @@ module Google
         ##
         # Creates a new {Subscription} object on the current Topic.
         #
-        # @param [String] subscription_name Name of the new subscription. Required.
+        # @option options [String] subscription_name Name of the new subscription. Required.
         #   The value can be a simple subscription ID (relative name), in which
         #   case the current project ID will be supplied, or a fully-qualified
         #   subscription name in the form
@@ -375,26 +375,27 @@ module Google
         #   underscores (`_`), periods (`.`), tildes (`~`), plus (`+`) or percent
         #   signs (`%`). It must be between 3 and 255 characters in length, and
         #   it must not start with `goog`.
-        # @param [Integer] deadline The maximum number of seconds after a
+        # @option options [Integer] deadline The maximum number of seconds after a
         #   subscriber receives a message before the subscriber should
         #   acknowledge the message.
-        # @param [Boolean] retain_acked Indicates whether to retain acknowledged
+        # @option options [Boolean] retain_acked Indicates whether to retain acknowledged
         #   messages. If `true`, then messages are not expunged from the
         #   subscription's backlog, even if they are acknowledged, until they
         #   fall out of the `retention` window. Default is `false`.
-        # @param [Numeric] retention How long to retain unacknowledged messages
+        # @option options [Numeric] retention How long to retain unacknowledged messages
         #   in the subscription's backlog, from the moment a message is
         #   published. If `retain_acked` is `true`, then this also configures
         #   the retention of acknowledged messages, and thus configures how far
         #   back in time a {Subscription#seek} can be done. Cannot be more than
         #   604,800 seconds (7 days) or less than 600 seconds (10 minutes).
         #   Default is 604,800 seconds (7 days).
-        # @param [String] endpoint A URL locating the endpoint to which messages
+        # @option options [String] endpoint A URL locating the endpoint to which messages
         #   should be pushed. The parameters `push_config` and `endpoint` should not both be provided.
-        # @param [Google::Cloud::PubSub::Subscription::PushConfig] push_config The configuration for a push delivery
-        #   endpoint that should contain the endpoint, and can contain authentication data (OIDC token authentication).
-        #   The parameters `push_config` and `endpoint` should not both be provided.
-        # @param [Hash] labels A hash of user-provided labels associated with
+        # @option options [Google::Cloud::PubSub::Subscription::PushConfig] push_config
+        #  The configuration for a push delivery endpoint that should contain the endpoint,
+        #  and can contain authentication data (OIDC token authentication).
+        #  The parameters `push_config` and `endpoint` should not both be provided.
+        # @option options [Hash] labels A hash of user-provided labels associated with
         #   the subscription. You can use these to organize and group your
         #   subscriptions. Label keys and values can be no longer than 63
         #   characters, can only contain lowercase letters, numeric characters,
@@ -402,25 +403,29 @@ module Google
         #   values are optional. Label keys must start with a letter and each
         #   label in the list must have a different key. See [Creating and
         #   Managing Labels](https://cloud.google.com/pubsub/docs/labels).
-        # @param [Boolean] message_ordering Whether to enable message ordering
+        # @option options [Boolean] message_ordering Whether to enable message ordering
         #   on the subscription.
-        # @param [String] filter An expression written in the Cloud Pub/Sub filter language. If non-empty, then only
-        #   {Message} instances whose `attributes` field matches the filter are delivered on this subscription. If
+        # @option options [String] filter An expression written in the Cloud Pub/Sub filter language.
+        #   If non-empty, then only {Message} instances whose `attributes` field
+        #   matches the filter are delivered on this subscription. If
         #   empty, then no messages are filtered out. Optional.
-        # @param [Topic] dead_letter_topic The {Topic} to which dead letter messages for the subscription should be
-        #   published. Dead lettering is done on a best effort basis. The same message might be dead lettered multiple
+        # @option options [Topic] dead_letter_topic
+        #   The {Topic} to which dead letter messages for the subscription should be published.
+        #   Dead lettering is done on a best effort basis. The same message might be dead lettered multiple
         #   times. The Cloud Pub/Sub service account associated with the enclosing subscription's parent project (i.e.,
         #   `service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to
         #   this topic.
         #
         #   The operation will fail if the topic does not exist. Users should ensure that there is a subscription
         #   attached to this topic since messages published to a topic with no subscriptions are lost.
-        # @param [Integer] dead_letter_max_delivery_attempts The maximum number of delivery attempts for any message in
-        #   the subscription's dead letter policy. Dead lettering is done on a best effort basis. The same message might
+        # @option options [Integer] dead_letter_max_delivery_attempts
+        #   The maximum number of delivery attempts for any message in the subscription's dead letter policy.
+        #   Dead lettering is done on a best effort basis. The same message might
         #   be dead lettered multiple times. The value must be between 5 and 100. If this parameter is 0, a default
         #   value of 5 is used. The `dead_letter_topic` must also be set.
-        # @param [RetryPolicy] retry_policy A policy that specifies how Cloud Pub/Sub retries message delivery for
-        #   this subscription. If not set, the default retry policy is applied. This generally implies that messages
+        # @option options [RetryPolicy] retry_policy
+        #   A policy that specifies how Cloud Pub/Sub retries message delivery for this subscription.
+        #   If not set, the default retry policy is applied. This generally implies that messages
         #   will be retried as soon as possible for healthy subscribers. Retry Policy will be triggered on NACKs or
         #   acknowledgement deadline exceeded events for a given message.
         #
@@ -486,41 +491,23 @@ module Google
         #   retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
         #   sub = topic.subscribe "my-topic-sub", retry_policy: retry_policy
         #
-        def subscribe subscription_name,
-                      deadline: nil,
-                      retain_acked: false,
-                      retention: nil,
-                      endpoint: nil,
-                      push_config: nil,
-                      labels: nil,
-                      message_ordering: nil,
-                      filter: nil,
-                      dead_letter_topic: nil,
-                      dead_letter_max_delivery_attempts: nil,
-                      retry_policy: nil
+        def subscribe subscription_name, **options
           ensure_service!
-          if push_config && endpoint
+          if options[:push_config] && options[:endpoint]
             raise ArgumentError, "endpoint and push_config were both provided. Please provide only one."
           end
-          push_config = Google::Cloud::PubSub::Subscription::PushConfig.new endpoint: endpoint if endpoint
-
-          options = {
-            deadline:                          deadline,
-            retain_acked:                      retain_acked,
-            retention:                         retention,
-            labels:                            labels,
-            message_ordering:                  message_ordering,
-            filter:                            filter,
-            dead_letter_max_delivery_attempts: dead_letter_max_delivery_attempts
-          }
+          if options[:endpoint]
+            options[:push_config] =
+              Google::Cloud::PubSub::Subscription::PushConfig.new endpoint: options[:endpoint]
+          end
 
-          options[:dead_letter_topic_name] = dead_letter_topic.name if dead_letter_topic
+          options[:dead_letter_topic_name] = options[:dead_letter_topic].name if options[:dead_letter_topic]
           if options[:dead_letter_max_delivery_attempts] && !options[:dead_letter_topic_name]
             # Service error message "3:Invalid resource name given (name=)." does not identify param.
             raise ArgumentError, "dead_letter_topic is required with dead_letter_max_delivery_attempts"
           end
-          options[:push_config] = push_config.to_grpc if push_config
-          options[:retry_policy] = retry_policy.to_grpc if retry_policy
+          options[:push_config] = options[:push_config].to_grpc if options[:push_config]
+          options[:retry_policy] = options[:retry_policy].to_grpc if options[:retry_policy]
           grpc = service.create_subscription name, subscription_name, options
           Subscription.from_grpc grpc, service
         end

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module PubSub
-      VERSION = "2.10.0".freeze
+      VERSION = "2.11.0".freeze
     end
 
     Pubsub = PubSub unless const_defined? :Pubsub

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-pubsub
 version: !ruby/object:Gem::Version
-  version: 2.10.0
+  version: 2.11.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-06-15 00:00:00.000000000 Z
+date: 2022-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -53,6 +53,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.0'
+- !ruby/object:Gem::Dependency
+  name: retriable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
 - !ruby/object:Gem::Dependency
   name: autotest-suffix
   requirement: !ruby/object:Gem::Requirement
@@ -101,14 +115,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.14'
+        version: '5.16'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.14'
+        version: '5.16'
 - !ruby/object:Gem::Dependency
   name: minitest-autotest
   requirement: !ruby/object:Gem::Requirement
@@ -227,6 +241,7 @@ files:
 - TROUBLESHOOTING.md
 - lib/google-cloud-pubsub.rb
 - lib/google/cloud/pubsub.rb
+- lib/google/cloud/pubsub/acknowledge_result.rb
 - lib/google/cloud/pubsub/async_publisher.rb
 - lib/google/cloud/pubsub/async_publisher/batch.rb
 - lib/google/cloud/pubsub/batch_publisher.rb