google-cloud-pubsub 3.4.1 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae1f8eddfa934835b8fc01e2a85606f9c93f7b353ca5b8d3ba328af3fc5e3cdc
-  data.tar.gz: 70d186ba6e4b8e8114ca6f2184d726acff47311f05906a51662227457c3ef6a1
+  metadata.gz: 5694017436fe99de18ba1d45e73ecdb0941b0183e115c3d02cad10085dcaae2c
+  data.tar.gz: b4a7a35193d6b9e75614474dc6510d1c978bbaa49fc2973123da33ea38b33116
 SHA512:
-  metadata.gz: 0d199c7bda57c229e349ceeb21d38311c6388047ba728caaf8967e7cec0076a17af6dd55b1e0cbaad88a8a81ffdeed4814c367c617a25a643986b4a929a12cfe
-  data.tar.gz: cbfc81b692b367245d4d9b94282833805ee706588d61d2277bbfcfb4fff74e8b17c4aeae246f50e7d0f26f3f07b1862be088c42e92baf8b25ec7a47eb9302b73
+  metadata.gz: f49b732799a033333beef767ac6667d603d066ff5bc5f7207b7c05ab127a4996e95f472a9377826ac2fc5898f6b31f710d2408473f611b1114815968edd91f95
+  data.tar.gz: 3cb7429db18f8d79c4ff6d1b0a1e488ebf090268fcb9e7ad35f19f4dced3e77c1616c89a8b6d070a9e9e4fc9fd57a3db0cdff2fb44cfc4f8432e57fe6c8719d2

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History
 
+### 3.5.0 (2026-09-14)
+
+#### Features
+
+* Support subscriber shutdown options ([#36480](https://github.com/googleapis/google-cloud-ruby/issues/36480)) 
+#### Documentation
+
+* Add subscriber shutdown documentation and examples ([#36482](https://github.com/googleapis/google-cloud-ruby/issues/36482)) 
+
 ### 3.4.1 (2026-08-24)
 
 #### Bug Fixes

data/lib/google/cloud/pubsub/message_listener/inventory.rb

@@ -50,7 +50,7 @@ module Google
           end
 
           def ack_ids
-            @inventory.keys
+            synchronize { @inventory.keys }
           end
 
           def add *rec_msgs
@@ -109,6 +109,31 @@ module Google
             end
           end
 
+          ##
+          # @private
+          # Blocks until the inventory is empty or until timeout expires.
+          #
+          # @param [Numeric, nil] timeout Maximum time in seconds to wait, or nil to wait indefinitely.
+          # @return [Boolean] true if inventory became empty, false if timed out.
+          def wait_until_empty timeout = nil
+            synchronize do
+              return true if @inventory.empty?
+
+              if timeout
+                target_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+                while !@inventory.empty? && !@stopped
+                  remaining = target_time - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+                  break if remaining <= 0
+
+                  @wait_cond.wait remaining
+                end
+              else
+                @wait_cond.wait_while { !@inventory.empty? && !@stopped }
+              end
+              @inventory.empty?
+            end
+          end
+
           def start
             @background_thread ||= Thread.new { background_run }
 

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

@@ -111,6 +111,11 @@ module Google
             self
           end
 
+          ##
+          # @private
+          # Stops pulling messages from the subscription.
+          #
+          # @return [Stream] self for chaining.
           def stop
             synchronize do
               break if @stopped
@@ -129,22 +134,45 @@ module Google
 
               @keepalive_monitor.stop
 
-              # Now that the reception thread is stopped, immediately stop the
-              # callback thread pool. All queued callbacks will see the stream
-              # is stopped and perform a noop.
-              @callback_thread_pool.shutdown
-
-              # Once all the callbacks are stopped, we can stop the inventory.
-              @inventory.stop
+              # When :nack_immediately, release all queued messages immediately and shut down callback pool.
+              if nack_immediately?
+                nack_unprocessed_messages!
+                @callback_thread_pool.shutdown
+              end
             end
 
             self
           end
 
+          ##
+          # @private
+          # Nacks all messages currently held in inventory.
+          def nack_unprocessed_messages!
+            synchronize do
+              ack_ids = @inventory.ack_ids
+              return if ack_ids.empty?
+
+              @subscriber.buffer.modify_ack_deadline 0, ack_ids
+              @subscriber.buffer.flush!
+              @inventory.remove ack_ids
+            end
+          end
+
           def stopped?
             synchronize { @stopped }
           end
 
+          ##
+          # @private
+          # Returns whether the subscriber is stopped and configured to nack unprocessed messages immediately.
+          #
+          # @return [Boolean]
+          def nack_immediately?
+            return false unless @stopped
+
+            @subscriber.shutdown_behavior == :nack_immediately
+          end
+
           def stream_open?
             synchronize { @stream_open }
           end
@@ -157,14 +185,26 @@ module Google
             !stopped?
           end
 
+          ##
+          # @private
+          # Blocks until all received messages are processed, or until timeout expires.
+          #
+          # @param [Numeric, nil] timeout The maximum seconds to wait, or nil to wait indefinitely.
+          # @return [Stream] self for chaining.
           def wait! timeout = nil
-            # Wait for all queued callbacks to be processed.
-            @callback_thread_pool.wait_for_termination timeout
+            deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout if timeout
+            emptied = @inventory.wait_until_empty timeout
+            nack_unprocessed_messages! unless emptied
 
+            @callback_thread_pool.shutdown
+            pool_timeout = [deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max if deadline
+            @callback_thread_pool.wait_for_termination pool_timeout
+
+            # Once all callbacks are finished and inventory is clear, stop the inventory.
+            @inventory.stop
             self
           end
 
-
           def request_queue_active?
             !@request_queue.nil?
           end
@@ -466,7 +506,7 @@ module Google
             subscriber.service.internal_logger.log :info, "callback-delivery" do
               "message (ID #{rec_msg.message_id}, ackID #{rec_msg.ack_id}) delivery to user callbacks"
             end
-            @subscriber.callback.call rec_msg unless stopped?
+            @subscriber.callback.call rec_msg unless nack_immediately?
           rescue StandardError => e
             subscriber.service.internal_logger.log :info, "callback-exceptions" do
               "message (ID #{rec_msg.message_id}, ackID #{rec_msg.ack_id}) caused a user callback exception: " \
@@ -475,7 +515,7 @@ module Google
             @subscriber.error! e
           ensure
             release rec_msg
-            if @sequencer && running?
+            if @sequencer && !nack_immediately?
               begin
                 @sequencer.next rec_msg
               rescue OrderedMessageDeliveryError => e

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

@@ -60,6 +60,12 @@ module Google
       #   acknowledgement ({ReceivedMessage#ack!}) and delay messages
       #   ({ReceivedMessage#nack!}, {ReceivedMessage#modify_ack_deadline!}).
       #   Default is 4.
+      # @attr_reader [Symbol] shutdown_behavior The strategy used to handle
+      #   unprocessed messages when stopping the subscriber (`:wait_for_processing`
+      #   or `:nack_immediately`). Default is `:wait_for_processing`.
+      # @attr_reader [Numeric, nil] shutdown_timeout The maximum number of
+      #   seconds to wait during shutdown before forcing remaining messages
+      #   to be nacked. Default is `nil`.
       #
       class MessageListener
         include MonitorMixin
@@ -71,6 +77,8 @@ module Google
         attr_reader :message_ordering
         attr_reader :callback_threads
         attr_reader :push_threads
+        attr_reader :shutdown_behavior
+        attr_reader :shutdown_timeout
 
         ##
         # @private Implementation attributes.
@@ -83,7 +91,7 @@ module Google
         ##
         # @private Create an empty {MessageListener} object.
         def initialize subscription_name, callback, deadline: nil, message_ordering: nil, streams: nil, inventory: nil,
-                       threads: {}, service: nil
+                       threads: {}, shutdown_behavior: :wait_for_processing, shutdown_timeout: nil, service: nil
           super() # to init MonitorMixin
 
           @callback = callback
@@ -91,6 +99,16 @@ module Google
           @subscription_name = subscription_name
           @deadline = deadline || 60
           @streams = streams || 1
+          @shutdown_behavior = shutdown_behavior || :wait_for_processing
+          @shutdown_timeout = shutdown_timeout
+
+          unless [:wait_for_processing, :nack_immediately].include? @shutdown_behavior
+            raise ArgumentError, "Invalid shutdown_behavior: #{@shutdown_behavior.inspect}"
+          end
+          if @shutdown_timeout && (!@shutdown_timeout.is_a?(Numeric) || @shutdown_timeout.negative?)
+            raise ArgumentError, "Invalid shutdown_timeout: #{@shutdown_timeout.inspect}"
+          end
+
           coerce_inventory inventory
           @message_ordering = message_ordering
           @callback_threads = Integer(threads[:callback] || 8)
@@ -145,7 +163,7 @@ module Google
             @started = false
             @stopped = true
             @stream_pool.map(&:stop)
-            wait_stop_buffer_thread!
+            wait_stop_buffer_thread! @shutdown_timeout
             self
           end
         end
@@ -160,12 +178,14 @@ module Google
         # stopped.
         #
         # @param [Number, nil] timeout The number of seconds to block until the
-        #   subscriber is fully stopped. Default will block indefinitely.
+        #   subscriber is fully stopped. Default will block indefinitely or use
+        #   configured `shutdown_timeout`.
         #
         # @return [MessageListener] returns self so calls can be chained.
         #
         def wait! timeout = nil
-          wait_stop_buffer_thread!
+          timeout ||= @shutdown_timeout
+          wait_stop_buffer_thread! timeout
           @wait_stop_buffer_thread.join timeout
           self
         end
@@ -178,11 +198,13 @@ module Google
         # The same as calling {#stop} and {#wait!}.
         #
         # @param [Number, nil] timeout The number of seconds to block until the
-        #   listener is fully stopped. Default will block indefinitely.
+        #   listener is fully stopped. Default will block indefinitely or use
+        #   configured `shutdown_timeout`.
         #
         # @return [MessageListener] returns self so calls can be chained.
         #
         def stop! timeout = nil
+          timeout ||= @shutdown_timeout
           stop
           wait! timeout
         end
@@ -365,10 +387,10 @@ module Google
 
         ##
         # Starts a new thread to call wait! (blocking) on each Stream and then stop the TimedUnaryBuffer.
-        def wait_stop_buffer_thread!
+        def wait_stop_buffer_thread! timeout = nil
           synchronize do
             @wait_stop_buffer_thread ||= Thread.new do
-              @stream_pool.map(&:wait!)
+              @stream_pool.each { |s| s.wait! timeout }
               # Shutdown the buffer TimerTask (and flush the buffer) after the streams are all stopped.
               @buffer.stop
             end

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

@@ -324,6 +324,16 @@ module Google
         #       acknowledgement ({ReceivedMessage#ack!}) and modify ack deadline
         #       messages ({ReceivedMessage#nack!},
         #       {ReceivedMessage#modify_ack_deadline!}). Default is 4.
+        # @param [Symbol] shutdown_behavior The strategy used to handle
+        #   unprocessed messages when stopping the subscriber.
+        #   Supported values:
+        #   * `:wait_for_processing` (default) - Waits for in-flight callbacks
+        #     to complete and acknowledge or nack messages.
+        #   * `:nack_immediately` - Immediately nacks all unprocessed messages
+        #     back to Pub/Sub for rapid redelivery to other subscribers.
+        # @param [Numeric, nil] shutdown_timeout The maximum number of seconds
+        #   to wait during shutdown before forcing remaining in-flight messages
+        #   to be nacked. Default is `nil` (blocks indefinitely until callbacks finish).
         #
         # @yield [received_message] a block for processing new messages
         # @yieldparam [ReceivedMessage] received_message the newly received
@@ -408,13 +418,52 @@ module Google
         #   # Shut down the subscriber when ready to stop receiving messages.
         #   listener.stop!
         #
-        def listen deadline: nil, message_ordering: nil, streams: nil, inventory: nil, threads: {}, &block
+        # @example Immediately release unprocessed messages on shutdown:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   subscriber = pubsub.subscriber "my-topic-sub"
+        #
+        #   listener = subscriber.listen shutdown_behavior: :nack_immediately do |received_message|
+        #     # process message
+        #     puts "Data: #{received_message.message.data}"
+        #     received_message.acknowledge!
+        #   end
+        #
+        #   listener.start
+        #
+        #   # Shut down immediately, releasing (nacking) any unprocessed messages
+        #   listener.stop!
+        #
+        # @example Gracefully shut down with a custom timeout:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   subscriber = pubsub.subscriber "my-topic-sub"
+        #
+        #   listener = subscriber.listen shutdown_behavior: :wait_for_processing, shutdown_timeout: 30 do |received_message|
+        #     # process message
+        #     puts "Data: #{received_message.message.data}"
+        #     received_message.acknowledge!
+        #   end
+        #
+        #   listener.start
+        #
+        #   # Wait up to 30 seconds for in-flight callbacks before forcing remaining to nack
+        #   listener.stop!
+        #
+        def listen deadline: nil, message_ordering: nil, streams: nil, inventory: nil, threads: {},
+                   shutdown_behavior: :wait_for_processing, shutdown_timeout: nil, &block
           ensure_service!
           deadline ||= self.deadline
           message_ordering = message_ordering? if message_ordering.nil?
 
           MessageListener.new name, block, deadline: deadline, streams: streams, inventory: inventory,
-                                      message_ordering: message_ordering, threads: threads, service: service
+                                      message_ordering: message_ordering, threads: threads,
+                                      shutdown_behavior: shutdown_behavior, shutdown_timeout: shutdown_timeout,
+                                      service: service
         end
 
         ##

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module PubSub
-      VERSION = "3.4.1".freeze
+      VERSION = "3.5.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: 3.4.1
+  version: 3.5.0
 platform: ruby
 authors:
 - Mike Moore