google-cloud-pubsub 1.1.3 → 1.10.0

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

@@ -181,8 +181,8 @@ module Google
             synchronize do
               return true if @inventory.empty?
 
-              @subscriber.buffer.renew_lease @subscriber.deadline,
-                                             @inventory.ack_ids
+              @inventory.remove_expired!
+              @subscriber.buffer.renew_lease @subscriber.deadline, @inventory.ack_ids
               unpause_streaming!
             end
 
@@ -243,17 +243,13 @@ module Google
                 # Cannot syncronize the enumerator, causes deadlock
                 response = enum.next
 
-                # Create a list of all the received ack_id values
-                received_ack_ids = response.received_messages.map(&:ack_id)
-
                 # Use synchronize so both changes happen atomically
                 synchronize do
                   # Create receipt of received messages reception
-                  @subscriber.buffer.modify_ack_deadline @subscriber.deadline,
-                                                         received_ack_ids
+                  @subscriber.buffer.modify_ack_deadline @subscriber.deadline, response.received_messages.map(&:ack_id)
 
                   # Add received messages to inventory
-                  @inventory.add received_ack_ids
+                  @inventory.add response.received_messages
                 end
 
                 response.received_messages.each do |rec_msg_grpc|
@@ -367,6 +363,9 @@ module Google
               req.stream_ack_deadline_seconds = @subscriber.deadline
               req.modify_deadline_ack_ids += @inventory.ack_ids
               req.modify_deadline_seconds += @inventory.ack_ids.map { @subscriber.deadline }
+              req.client_id = @subscriber.service.client_id
+              req.max_outstanding_messages = @inventory.limit
+              req.max_outstanding_bytes = @inventory.bytesize
             end
           end
 

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

@@ -54,8 +54,6 @@ module Google
       #   been enabled.
       # @attr_reader [Integer] streams The number of concurrent streams to open
       #   to pull messages from the subscription. Default is 4.
-      # @attr_reader [Integer] inventory The number of received messages to be
-      #   collected by subscriber. Default is 1,000.
       # @attr_reader [Integer] callback_threads The number of threads used to
       #   handle the received messages. Default is 8.
       # @attr_reader [Integer] push_threads The number of threads to handle
@@ -66,19 +64,16 @@ module Google
       class Subscriber
         include MonitorMixin
 
-        attr_reader :subscription_name, :callback, :deadline, :streams,
-                    :inventory, :message_ordering, :callback_threads,
+        attr_reader :subscription_name, :callback, :deadline, :streams, :message_ordering, :callback_threads,
                     :push_threads
 
         ##
         # @private Implementation attributes.
-        attr_reader :stream_inventory, :stream_pool, :thread_pool, :buffer,
-                    :service
+        attr_reader :stream_pool, :thread_pool, :buffer, :service
 
         ##
         # @private Create an empty {Subscriber} object.
-        def initialize subscription_name, callback, deadline: nil,
-                       message_ordering: nil, streams: nil, inventory: nil,
+        def initialize subscription_name, callback, deadline: nil, message_ordering: nil, streams: nil, inventory: nil,
                        threads: {}, service: nil
           super() # to init MonitorMixin
 
@@ -86,17 +81,15 @@ module Google
           @error_callbacks = []
           @subscription_name = subscription_name
           @deadline = deadline || 60
-          @streams = streams || 4
-          @inventory = inventory || 1000
+          @streams = streams || 2
+          coerce_inventory inventory
           @message_ordering = message_ordering
-          @callback_threads = (threads[:callback] || 8).to_i
-          @push_threads = (threads[:push] || 4).to_i
+          @callback_threads = Integer(threads[:callback] || 8)
+          @push_threads = Integer(threads[:push] || 4)
 
-          @stream_inventory = @inventory.fdiv(@streams).ceil
           @service = service
 
-          @started = nil
-          @stopped = nil
+          @started = @stopped = nil
 
           stream_pool = Array.new @streams do
             Thread.new { Stream.new self }
@@ -111,6 +104,7 @@ module Google
         # received messages.
         #
         # @return [Subscriber] returns self so calls can be chained.
+        #
         def start
           start_pool = synchronize do
             @started = true
@@ -136,6 +130,7 @@ module Google
         # received messages have been processed or released.
         #
         # @return [Subscriber] returns self so calls can be chained.
+        #
         def stop
           stop_pool = synchronize do
             @started = false
@@ -165,6 +160,7 @@ module Google
         #   subscriber is fully stopped. Default will block indefinitely.
         #
         # @return [Subscriber] returns self so calls can be chained.
+        #
         def wait! timeout = nil
           wait_pool = synchronize do
             @stream_pool.map do |stream|
@@ -197,6 +193,7 @@ module Google
         # Whether the subscriber has been started.
         #
         # @return [boolean] `true` when started, `false` otherwise.
+        #
         def started?
           synchronize { @started }
         end
@@ -205,6 +202,7 @@ module Google
         # Whether the subscriber has been stopped.
         #
         # @return [boolean] `true` when stopped, `false` otherwise.
+        #
         def stopped?
           synchronize { @stopped }
         end
@@ -284,6 +282,62 @@ module Google
           synchronize { @last_error }
         end
 
+        ##
+        # The number of received messages to be collected by subscriber. Default is 1,000.
+        #
+        # @return [Integer] The maximum number of messages.
+        #
+        def max_outstanding_messages
+          @inventory[:max_outstanding_messages]
+        end
+        # @deprecated Use {#max_outstanding_messages}.
+        alias inventory_limit max_outstanding_messages
+        # @deprecated Use {#max_outstanding_messages}.
+        alias inventory max_outstanding_messages
+
+        ##
+        # The total byte size of received messages to be collected by subscriber. Default is 100,000,000 (100MB).
+        #
+        # @return [Integer] The maximum number of bytes.
+        #
+        def max_outstanding_bytes
+          @inventory[:max_outstanding_bytes]
+        end
+        # @deprecated Use {#max_outstanding_bytes}.
+        alias inventory_bytesize max_outstanding_bytes
+
+        ##
+        # The number of seconds that received messages can be held awaiting processing. Default is 3,600 (1 hour).
+        #
+        # @return [Integer] The maximum number of seconds.
+        #
+        def max_total_lease_duration
+          @inventory[:max_total_lease_duration]
+        end
+        # @deprecated Use {#max_total_lease_duration}.
+        alias inventory_extension max_total_lease_duration
+
+        ##
+        # The maximum amount of time in seconds for a single lease extension attempt. Bounds the delay before a message
+        # redelivery if the subscriber fails to extend the deadline. Default is 0 (disabled).
+        #
+        # @return [Integer] The maximum number of seconds.
+        #
+        def max_duration_per_lease_extension
+          @inventory[:max_duration_per_lease_extension]
+        end
+
+        ##
+        # @private
+        def stream_inventory
+          {
+            limit:                            @inventory[:max_outstanding_messages].fdiv(@streams).ceil,
+            bytesize:                         @inventory[:max_outstanding_bytes].fdiv(@streams).ceil,
+            extension:                        @inventory[:max_total_lease_duration],
+            max_duration_per_lease_extension: @inventory[:max_duration_per_lease_extension]
+          }
+        end
+
         # @private returns error object from the stream thread.
         def error! error
           error_callbacks = synchronize do
@@ -308,6 +362,23 @@ module Google
 
         protected
 
+        def coerce_inventory inventory
+          @inventory = inventory
+          if @inventory.is_a? Hash
+            @inventory = @inventory.dup
+            # Support deprecated field names
+            @inventory[:max_outstanding_messages] ||= @inventory.delete :limit
+            @inventory[:max_outstanding_bytes] ||= @inventory.delete :bytesize
+            @inventory[:max_total_lease_duration] ||= @inventory.delete :extension
+          else
+            @inventory = { max_outstanding_messages: @inventory }
+          end
+          @inventory[:max_outstanding_messages] = Integer(@inventory[:max_outstanding_messages] || 1000)
+          @inventory[:max_outstanding_bytes] = Integer(@inventory[:max_outstanding_bytes] || 100_000_000)
+          @inventory[:max_total_lease_duration] = Integer(@inventory[:max_total_lease_duration] || 3600)
+          @inventory[:max_duration_per_lease_extension] = Integer(@inventory[:max_duration_per_lease_extension] || 0)
+        end
+
         def default_error_callbacks
           # This is memoized to reduce calls to the configuration.
           @default_error_callbacks ||= begin

data/lib/google/cloud/pubsub/subscription/push_config.rb

@@ -52,7 +52,7 @@ module Google
 
           ##
           # A URL locating the endpoint to which messages should be pushed. For
-          # example, a Webhook endpoint might use "https://example.com/push".
+          # example, a Webhook endpoint might use `https://example.com/push`.
           #
           # @return [String]
           def endpoint
@@ -62,7 +62,7 @@ module Google
           ##
           # Sets the URL locating the endpoint to which messages should be
           # pushed. For example, a Webhook endpoint might use
-          # "https://example.com/push".
+          # `https://example.com/push`.
           #
           # @param [String, nil] new_endpoint New URL value
           def endpoint= new_endpoint

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

@@ -18,8 +18,10 @@ require "google/cloud/errors"
 require "google/cloud/pubsub/subscription/list"
 require "google/cloud/pubsub/subscription/push_config"
 require "google/cloud/pubsub/received_message"
+require "google/cloud/pubsub/retry_policy"
 require "google/cloud/pubsub/snapshot"
 require "google/cloud/pubsub/subscriber"
+require "google/cloud/pubsub/v1"
 
 module Google
   module Cloud
@@ -187,7 +189,7 @@ module Google
         ##
         # Returns the URL locating the endpoint to which messages should be
         # pushed. For example, a Webhook endpoint might use
-        # "https://example.com/push".
+        # `https://example.com/push`.
         #
         # Makes an API call to retrieve the endpoint value when called on a
         # reference object. See {#reference?}.
@@ -201,7 +203,7 @@ module Google
 
         ##
         # Sets the URL locating the endpoint to which messages should be pushed.
-        # For example, a Webhook endpoint might use "https://example.com/push".
+        # For example, a Webhook endpoint might use `https://example.com/push`.
         #
         # @param [String] new_endpoint The new endpoint value.
         #
@@ -321,7 +323,7 @@ module Google
         # If {#expires_in=} is not set, a *default* value of of 31 days will be
         # used. The minimum allowed value is 1 day.
         #
-        # Makes an API call to retrieve the labels value when called on a
+        # Makes an API call to retrieve the value when called on a
         # reference object. See {#reference?}.
         #
         # @return [Numeric, nil] The expiration duration, or `nil` if unset.
@@ -351,6 +353,208 @@ module Google
           @resource_name = nil
         end
 
+        ##
+        # 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.
+        #
+        # @return [String] The frozen filter string.
+        #
+        def filter
+          ensure_grpc!
+          @grpc.filter.freeze
+        end
+
+        ##
+        # Returns the {Topic} to which dead letter messages should be published if a dead letter policy is configured,
+        # otherwise `nil`. Dead lettering is done on a best effort basis. The same message might be dead lettered
+        # multiple times.
+        #
+        # See also {#dead_letter_topic=}, {#dead_letter_max_delivery_attempts=} and
+        # {#dead_letter_max_delivery_attempts}.
+        #
+        # Makes an API call to retrieve the topic name when called on a reference object. See {#reference?}.
+        #
+        # @return [Topic, nil]
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
+        #   sub.dead_letter_max_delivery_attempts #=> 10
+        #
+        def dead_letter_topic
+          ensure_grpc!
+          return nil unless @grpc.dead_letter_policy
+          Topic.from_name @grpc.dead_letter_policy.dead_letter_topic, service
+        end
+
+        ##
+        # Sets 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.
+        #
+        # See also {#dead_letter_topic}, {#dead_letter_max_delivery_attempts=} and {#dead_letter_max_delivery_attempts}.
+        #
+        # @param [Topic] new_dead_letter_topic The topic to which dead letter messages for the subscription should be
+        #   published.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   dead_letter_topic = pubsub.topic "my-dead-letter-topic", skip_lookup: true
+        #   sub.dead_letter_topic = dead_letter_topic
+        #
+        def dead_letter_topic= new_dead_letter_topic
+          ensure_grpc!
+          dead_letter_policy = @grpc.dead_letter_policy || Google::Cloud::PubSub::V1::DeadLetterPolicy.new
+          dead_letter_policy.dead_letter_topic = new_dead_letter_topic.name
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, dead_letter_policy: dead_letter_policy
+          @grpc = service.update_subscription update_grpc, :dead_letter_policy
+          @resource_name = nil
+        end
+
+        ##
+        # Returns the maximum number of delivery attempts for any message in the subscription's dead letter policy if a
+        # dead letter policy is configured, otherwise `nil`. 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.
+        #
+        # The number of delivery attempts is defined as 1 + (the sum of number of NACKs and number of times the
+        # acknowledgement deadline has been exceeded for the message). A NACK is any call to ModifyAckDeadline with a 0
+        # deadline. Note that client libraries may automatically extend ack_deadlines.
+        #
+        # This field will be honored on a best effort basis. If this parameter is 0, a default value of 5 is used.
+        #
+        # See also {#dead_letter_max_delivery_attempts=}, {#dead_letter_topic=} and {#dead_letter_topic}.
+        #
+        # Makes an API call to retrieve the value when called on a reference object. See {#reference?}.
+        #
+        # @return [Integer, nil] A value between 5 and 100, or `nil` if no dead letter policy is configured. If this
+        #   value is 0, a default value of 5 is used.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
+        #   sub.dead_letter_max_delivery_attempts #=> 10
+        #
+        def dead_letter_max_delivery_attempts
+          ensure_grpc!
+          @grpc.dead_letter_policy&.max_delivery_attempts
+        end
+
+        ##
+        # Sets 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.
+        #
+        # The number of delivery attempts is defined as 1 + (the sum of number of NACKs and number of times the
+        # acknowledgement deadline has been exceeded for the message). A NACK is any call to ModifyAckDeadline with a 0
+        # deadline. Note that client libraries may automatically extend ack_deadlines.
+        #
+        # This field will be honored on a best effort basis. If this parameter is 0, a default value of 5 is used.
+        #
+        # The dead letter topic must also be set. See {#dead_letter_topic=} and {#dead_letter_topic}.
+        #
+        # @param [Integer] new_dead_letter_max_delivery_attempts A value between 5 and 100. If this parameter is 0, a
+        #   default value of 5 is used.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
+        #
+        #   sub.dead_letter_max_delivery_attempts = 20
+        #
+        def dead_letter_max_delivery_attempts= new_dead_letter_max_delivery_attempts
+          ensure_grpc!
+          unless @grpc.dead_letter_policy&.dead_letter_topic
+            # 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
+          dead_letter_policy = @grpc.dead_letter_policy || Google::Cloud::PubSub::V1::DeadLetterPolicy.new
+          dead_letter_policy.max_delivery_attempts = new_dead_letter_max_delivery_attempts
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, dead_letter_policy: dead_letter_policy
+          @grpc = service.update_subscription update_grpc, :dead_letter_policy
+          @resource_name = nil
+        end
+
+        ##
+        # A policy that specifies how Cloud Pub/Sub retries message delivery for this subscription. If `nil`, 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.
+        #
+        # **EXPERIMENTAL:** This API might be changed in backward-incompatible ways and is not recommended for
+        # production use. It is not subject to any SLA or deprecation policy.
+        #
+        # @return [RetryPolicy, nil] The retry policy for the subscription, or `nil`.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #
+        #   sub.retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
+        #
+        #   sub.retry_policy.minimum_backoff #=> 5
+        #   sub.retry_policy.maximum_backoff #=> 300
+        #
+        def retry_policy
+          ensure_grpc!
+          return nil unless @grpc.retry_policy
+          RetryPolicy.from_grpc @grpc.retry_policy
+        end
+
+        ##
+        # Sets a policy that specifies how Cloud Pub/Sub retries message delivery for this subscription. If `nil`, 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.
+        #
+        # **EXPERIMENTAL:** This API might be changed in backward-incompatible ways and is not recommended for
+        # production use. It is not subject to any SLA or deprecation policy.
+        #
+        # @param [RetryPolicy, nil] new_retry_policy A new retry policy for the subscription, or `nil`.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #
+        #   sub.retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
+        #
+        #   sub.retry_policy.minimum_backoff #=> 5
+        #   sub.retry_policy.maximum_backoff #=> 300
+        #
+        def retry_policy= new_retry_policy
+          ensure_grpc!
+          new_retry_policy = new_retry_policy.to_grpc if new_retry_policy
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, retry_policy: new_retry_policy
+          @grpc = service.update_subscription update_grpc, :retry_policy
+        end
+
         ##
         # Whether message ordering has been enabled. When enabled, messages
         # published with the same `ordering_key` will be delivered in the order
@@ -362,7 +566,7 @@ module Google
         #
         # See {Topic#publish_async}, {#listen}, and {Message#ordering_key}.
         #
-        # Makes an API call to retrieve the retain_acked value when called on a
+        # Makes an API call to retrieve the enable_message_ordering value when called on a
         # reference object. See {#reference?}.
         #
         # @return [Boolean]
@@ -372,6 +576,35 @@ module Google
           @grpc.enable_message_ordering
         end
 
+        ##
+        # Whether the subscription is detached from its topic. Detached subscriptions don't receive messages from their
+        # topic and don't retain any backlog. {#pull} and {#listen} (pull and streaming pull) operations will raise
+        # `FAILED_PRECONDITION`. If the subscription is a push subscription (see {#push_config}), pushes to the endpoint
+        # will not be made. The default value is `false`.
+        #
+        # See {Topic#subscribe} and {#detach}.
+        #
+        # Makes an API call to retrieve the value when called on a
+        # reference object. See {#reference?}.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   sub.detach
+        #
+        #   # sleep 120
+        #   sub.detached? #=> true
+        #
+        def detached?
+          ensure_grpc!
+          @grpc.detached
+        end
+
         ##
         # Determines whether the subscription exists in the Pub/Sub service.
         #
@@ -419,6 +652,32 @@ module Google
           true
         end
 
+        ##
+        # Detaches a subscription from its topic. All messages retained in the subscription are dropped. Detached
+        # subscriptions don't receive messages from their topic and don't retain any backlog. Subsequent {#pull} and
+        # {#listen} (pull and streaming pull) operations will raise `FAILED_PRECONDITION`. If the subscription is a push
+        # subscription (see {#push_config}), pushes to the endpoint will stop. It may take a few minutes for the
+        # subscription's detached state to be reflected in subsequent calls to {#detached?}.
+        #
+        # @return [Boolean] Returns `true` if the detach operation was successful.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   sub.detach
+        #
+        #   # sleep 120
+        #   sub.detached? #=> true
+        #
+        def detach
+          ensure_service!
+          service.detach_subscription name
+          true
+        end
+
         ##
         # Pulls messages from the server. Returns an empty list if there are no
         # messages available in the backlog. Raises an ApiError with status
@@ -556,8 +815,20 @@ module Google
         #   argument is not provided. See {#reference?}.
         # @param [Integer] streams The number of concurrent streams to open to
         #   pull messages from the subscription. Default is 4. Optional.
-        # @param [Integer] inventory The number of received messages to be
-        #   collected by subscriber. Default is 1,000. Optional.
+        # @param [Hash, Integer] inventory The settings to control how received messages are to be handled by the
+        #   subscriber. When provided as an Integer instead of a Hash only the `limit` will be set. Optional.
+        #
+        #   Hash keys and values may include the following:
+        #
+        #     * `:max_outstanding_messages` [Integer] The number of received messages to be collected by subscriber.
+        #       Default is 1,000. (Note: replaces `:limit`, which is deprecated.)
+        #     * `:max_outstanding_bytes` [Integer] The total byte size of received messages to be collected by
+        #       subscriber. Default is 100,000,000 (100MB). (Note: replaces `:bytesize`, which is deprecated.)
+        #     * `:max_total_lease_duration` [Integer] The number of seconds that received messages can be held awaiting
+        #       processing. Default is 3,600 (1 hour). (Note: replaces `:extension`, which is deprecated.)
+        #     * `:max_duration_per_lease_extension` [Integer] The maximum amount of time in seconds for a single lease
+        #       extension attempt. Bounds the delay before a message redelivery if the subscriber fails to extend the
+        #       deadline. Default is 0 (disabled).
         # @param [Hash] threads The number of threads to create to handle
         #   concurrent calls by each stream opened by the subscriber. Optional.
         #
@@ -633,6 +904,25 @@ module Google
         #   # Shut down the subscriber when ready to stop receiving messages.
         #   subscriber.stop.wait!
         #
+        # @example Set the maximum amount of time before redelivery if the subscriber fails to extend the deadline:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #
+        #   subscriber = sub.listen inventory: { max_duration_per_lease_extension: 20 } do |received_message|
+        #     # Process message very slowly with possibility of failure.
+        #     process rec_message.data # takes minutes
+        #     rec_message.acknowledge!
+        #   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.wait!
+        #
         def listen deadline: nil, message_ordering: nil, streams: nil, inventory: nil, threads: {}, &block
           ensure_service!
           deadline ||= self.deadline