google-cloud-pubsub 1.0.2 → 2.19.0

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
@@ -41,12 +43,19 @@ module Google
       #     received_message.acknowledge!
       #   end
       #
-      #   # Start background threads that will call the block passed to listen.
-      #   subscriber.start
+      #   # Handle exceptions from listener
+      #   subscriber.on_error do |exception|
+      #      puts "Exception: #{exception.class} #{exception.message}"
+      #   end
       #
-      #   # Shut down the subscriber when ready to stop receiving messages.
-      #   subscriber.stop.wait!
+      #   # Gracefully shut down the subscriber
+      #   at_exit do
+      #     subscriber.stop!
+      #   end
       #
+      #   # Start background threads that will call the block passed to listen.
+      #   subscriber.start
+      #   sleep
       class Subscription
         ##
         # @private The Service object.
@@ -68,7 +77,9 @@ module Google
         ##
         # The name of the subscription.
         #
-        # @return [String]
+        # @return [String] A fully-qualified subscription name in the form
+        #   `projects/{project_id}/subscriptions/{subscription_id}`.
+        #
         def name
           return @resource_name if reference?
           @grpc.name
@@ -117,10 +128,8 @@ module Google
         # @param [Integer] new_deadline The new deadline value.
         #
         def deadline= new_deadline
-          update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
-            name: name, ack_deadline_seconds: new_deadline
-          @grpc = service.update_subscription update_grpc,
-                                              :ack_deadline_seconds
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, ack_deadline_seconds: new_deadline
+          @grpc = service.update_subscription update_grpc, :ack_deadline_seconds
           @resource_name = nil
         end
 
@@ -148,10 +157,9 @@ module Google
         #   value.
         #
         def retain_acked= new_retain_acked
-          update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
-            name: name, retain_acked_messages: !(!new_retain_acked)
-          @grpc = service.update_subscription update_grpc,
-                                              :retain_acked_messages
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name:                  name,
+                                                                    retain_acked_messages: !(!new_retain_acked)
+          @grpc = service.update_subscription update_grpc, :retain_acked_messages
           @resource_name = nil
         end
 
@@ -160,9 +168,8 @@ module Google
         # 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
-        # {#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).
+        # {#seek} can be done. Cannot be less than 600 (10 minutes) or more
+        # than 604,800 (7 days). Default is 604,800 seconds (7 days).
         #
         # Makes an API call to retrieve the retention value when called on a
         # reference object. See {#reference?}.
@@ -181,17 +188,34 @@ module Google
         #
         def retention= new_retention
           new_retention_duration = Convert.number_to_duration new_retention
-          update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
-            name: name, message_retention_duration: new_retention_duration
-          @grpc = service.update_subscription update_grpc,
-                                              :message_retention_duration
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name:                       name,
+                                                                    message_retention_duration: new_retention_duration
+          @grpc = service.update_subscription update_grpc, :message_retention_duration
           @resource_name = nil
         end
 
+        ##
+        # Indicates the minimum duration for which a message is retained after
+        # it is published to the subscription's topic. If this field is set,
+        # messages published to the subscription's topic in the last
+        # `topic_message_retention_duration` are always available to subscribers.
+        # Output only. See {Topic#retention}.
+        #
+        # Makes an API call to retrieve the retention value when called on a
+        # reference object. See {#reference?}.
+        #
+        # @return [Numeric, nil] The topic message retention duration in seconds,
+        #   or `nil` if not set.
+        #
+        def topic_retention
+          ensure_grpc!
+          Convert.duration_to_number @grpc.topic_message_retention_duration
+        end
+
         ##
         # 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?}.
@@ -200,12 +224,12 @@ module Google
         #
         def endpoint
           ensure_grpc!
-          @grpc.push_config.push_endpoint if @grpc.push_config
+          @grpc.push_config&.push_endpoint
         end
 
         ##
         # 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.
         #
@@ -271,8 +295,7 @@ module Google
             new_config = config.to_grpc
 
             if old_config != new_config # has the object been changed?
-              update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
-                name: name, push_config: new_config
+              update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, push_config: new_config
               @grpc = service.update_subscription update_grpc, :push_config
             end
           end
@@ -280,6 +303,56 @@ module Google
           config.freeze
         end
 
+        ##
+        # Inspect the Subscription's bigquery configuration settings. The
+        # configuration can be changed by modifying the values in the method's
+        # block.
+        #
+        # @yield [bigquery_config] a block for modifying the bigquery configuration
+        # @yieldparam [Google::Cloud::PubSub::V1::BigQueryConfig] bigquery_config
+        #
+        # @return [Google::Cloud::PubSub::V1::BigQueryConfig]
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   sub.bigquery_config.table #=> "my-project:dataset-id.table-id"
+        #   sub.bigquery_config.use_topic_schema #=> true
+        #   sub.bigquery_config.write_metadata #=> false
+        #
+        # @example Update the bigquery configuration by passing a block:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   sub = pubsub.subscription "my-subscription"
+        #
+        #   sub.bigquery_config do |bc|
+        #     bc.write_metadata = true
+        #     bc.use_topic_schema = false
+        #   end
+        #
+        def bigquery_config
+          ensure_service!
+
+          config = reference? ? Google::Cloud::PubSub::V1::BigQueryConfig.new : @grpc.bigquery_config
+
+          if block_given?
+            old_config = config.dup
+            yield config
+            new_config = config
+
+            if old_config != new_config # has the object been changed?
+              update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, bigquery_config: new_config
+              @grpc = service.update_subscription update_grpc, :bigquery_config
+            end
+          end
+
+          config.freeze
+        end
+
         ##
         # A hash of user-provided labels associated with this subscription.
         # Labels can be used to organize and group subscriptions.See [Creating
@@ -312,8 +385,7 @@ module Google
         #
         def labels= new_labels
           raise ArgumentError, "Value must be a Hash" if new_labels.nil?
-          update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
-            name: name, labels: new_labels
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, labels: new_labels
           @grpc = service.update_subscription update_grpc, :labels
           @resource_name = nil
         end
@@ -327,7 +399,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 expires_in value when called on a
         # reference object. See {#reference?}.
         #
         # @return [Numeric, nil] The expiration duration, or `nil` if unset.
@@ -350,16 +422,310 @@ module Google
         #   to unset.
         #
         def expires_in= ttl
-          new_expiration_policy = Google::Pubsub::V1::ExpirationPolicy.new(
-            ttl: Convert.number_to_duration(ttl)
-          )
+          new_expiration_policy = Google::Cloud::PubSub::V1::ExpirationPolicy.new ttl: Convert.number_to_duration(ttl)
 
-          update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
-            name: name, expiration_policy: new_expiration_policy
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, expiration_policy: new_expiration_policy
           @grpc = service.update_subscription update_grpc, :expiration_policy
           @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.
+        #
+        # Makes an API call to retrieve the filter value when called on a reference
+        # object. See {#reference?}.
+        #
+        # @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=}, {#dead_letter_max_delivery_attempts}
+        # and {#remove_dead_letter_policy}.
+        #
+        # 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.
+        #
+        # Makes an API call to retrieve the dead_letter_policy value when called on a
+        # reference object. See {#reference?}.
+        #
+        # See also {#dead_letter_topic}, {#dead_letter_max_delivery_attempts=}, {#dead_letter_max_delivery_attempts}
+        # and {#remove_dead_letter_policy}.
+        #
+        # @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 `nil` or `0`, a default value of `5`
+        # is used.
+        #
+        # See also {#dead_letter_max_delivery_attempts=}, {#dead_letter_topic=}, {#dead_letter_topic}
+        # and {#remove_dead_letter_policy}.
+        #
+        # Makes an API call to retrieve the dead_letter_policy 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.
+        #
+        # @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.
+        #
+        # Makes an API call to retrieve the dead_letter_policy when called on a reference object. See {#reference?}.
+        #
+        # The dead letter topic must be set first. See {#dead_letter_topic=}, {#dead_letter_topic} and
+        # {#remove_dead_letter_policy}.
+        #
+        # @param [Integer, nil] new_dead_letter_max_delivery_attempts A value between 5 and 100. If this parameter is
+        #   `nil` or `0`, a default value of 5 is used.
+        #
+        # @raise [ArgumentError] if the dead letter topic has not been set. See {#dead_letter_topic=}.
+        #
+        # @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
+
+        ##
+        # Removes an existing dead letter policy. A dead letter policy specifies the conditions for dead lettering
+        # messages in the subscription. If a dead letter policy is not set, dead lettering is disabled.
+        #
+        # Makes an API call to retrieve the dead_letter_policy when called on a reference object. See {#reference?}.
+        #
+        # See {#dead_letter_topic}, {#dead_letter_topic=}, {#dead_letter_max_delivery_attempts} and
+        # {#dead_letter_max_delivery_attempts=}.
+        #
+        # @return [Boolean] `true` if an existing dead letter policy was removed, `false` if no existing dead letter
+        #   policy was present.
+        #
+        # @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
+        #
+        #   sub.remove_dead_letter_policy
+        #
+        #   sub.dead_letter_topic #=> nil
+        #   sub.dead_letter_max_delivery_attempts #=> nil
+        #
+        def remove_dead_letter_policy
+          ensure_grpc!
+          return false if @grpc.dead_letter_policy.nil?
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, dead_letter_policy: nil
+          @grpc = service.update_subscription update_grpc, :dead_letter_policy
+          true
+        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.
+        #
+        # Makes an API call to retrieve the retry_policy when called on a reference object. See {#reference?}.
+        #
+        # @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.
+        #
+        # @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_service!
+          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
+          @resource_name = nil
+        end
+
+        ##
+        # Whether message ordering has been enabled. When enabled, messages
+        # published with the same `ordering_key` will be delivered in the order
+        # they were published. When disabled, messages may be delivered in any
+        # order.
+        #
+        # @note At the time of this release, ordering keys are not yet publicly
+        #   enabled and requires special project enablements.
+        #
+        # See {Topic#publish_async}, {#listen}, and {Message#ordering_key}.
+        #
+        # Makes an API call to retrieve the enable_message_ordering value when called on a
+        # reference object. See {#reference?}.
+        #
+        # @return [Boolean]
+        #
+        def message_ordering?
+          ensure_grpc!
+          @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 detached 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.
         #
@@ -408,19 +774,54 @@ module Google
         end
 
         ##
-        # Pulls messages from the server. Returns an empty list if there are no
-        # messages available in the backlog. Raises an ApiError with status
-        # `UNAVAILABLE` if there are too many concurrent pull requests pending
-        # for the given subscription.
+        # 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, blocking until messages are available
+        # when called with the `immediate: false` option, which is recommended
+        # to avoid adverse impacts on the performance of pull operations.
+        #
+        # Raises an API error with status `UNAVAILABLE` if there are too many
+        # concurrent pull requests pending for the given subscription.
         #
         # See also {#listen} for the preferred way to process messages as they
         # become available.
         #
-        # @param [Boolean] immediate When `true` the system will respond
-        #   immediately even if it is not able to return messages. When `false`
-        #   the system is allowed to wait until it can return least one message.
-        #   No messages are returned when a request times out. The default value
-        #   is `true`.
+        # @param [Boolean] immediate Whether to return immediately or block until
+        #   messages are available.
+        #
+        #   **Warning:** The default value of this field is `true`. However, sending
+        #   `true` is discouraged because it adversely impacts the performance of
+        #   pull operations. We recommend that users always explicitly set this field
+        #   to `false`.
+        #
+        #   If this field set to `true`, the system will respond immediately
+        #   even if it there are no messages available to return in the pull
+        #   response. Otherwise, the system may wait (for a bounded amount of time)
+        #   until at least one message is available, rather than returning no messages.
         #
         #   See also {#listen} for the preferred way to process messages as they
         #   become available.
@@ -430,31 +831,24 @@ module Google
         #
         # @return [Array<Google::Cloud::PubSub::ReceivedMessage>]
         #
-        # @example
+        # @example The `immediate: false` option is now recommended to avoid adverse impacts on pull operations:
         #   require "google/cloud/pubsub"
         #
         #   pubsub = Google::Cloud::PubSub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
-        #   sub.pull.each { |received_message| received_message.acknowledge! }
-        #
-        # @example A maximum number of messages returned can also be specified:
-        #   require "google/cloud/pubsub"
-        #
-        #   pubsub = Google::Cloud::PubSub.new
-        #
-        #   sub = pubsub.subscription "my-topic-sub"
-        #   sub.pull(max: 10).each do |received_message|
+        #   received_messages = sub.pull immediate: false
+        #   received_messages.each do |received_message|
         #     received_message.acknowledge!
         #   end
         #
-        # @example The call can block until messages are available:
+        # @example A maximum number of messages returned can also be specified:
         #   require "google/cloud/pubsub"
         #
         #   pubsub = Google::Cloud::PubSub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
-        #   received_messages = sub.pull immediate: false
+        #   received_messages = sub.pull immediate: false, max: 10
         #   received_messages.each do |received_message|
         #     received_message.acknowledge!
         #   end
@@ -508,17 +902,60 @@ module Google
         # message will be removed from the subscriber and made available for
         # redelivery after the callback is completed.
         #
+        # Google Cloud Pub/Sub ordering keys provide the ability to ensure
+        # related messages are sent to subscribers in the order in which they
+        # were published. Messages can be tagged with an ordering key, a string
+        # that identifies related messages for which publish order should be
+        # respected. The service guarantees that, for a given ordering key and
+        # publisher, messages are sent to subscribers in the order in which they
+        # were published. Ordering does not require sacrificing high throughput
+        # or scalability, as the service automatically distributes messages for
+        # different ordering keys across subscribers.
+        #
+        # To use ordering keys, the subscription must be created with message
+        # ordering enabled (See {Topic#subscribe} and {#message_ordering?})
+        # before calling {#listen}. When enabled, the subscriber will deliver
+        # messages with the same `ordering_key` in the order they were
+        # published.
+        #
+        # @note At the time of this release, ordering keys are not yet publicly
+        #   enabled and requires special project enablements.
+        #
         # @param [Numeric] deadline The default number of seconds the stream
         #   will hold received messages before modifying the message's ack
         #   deadline. The minimum is 10, the maximum is 600. Default is
         #   {#deadline}. Optional.
         #
-        #   Makes an API call to retrieve the deadline value when called on a
-        #   reference object. See {#reference?}.
+        #   When using a reference object an API call will be made to retrieve
+        #   the default deadline value for the subscription when this argument
+        #   is not provided. See {#reference?}.
+        # @param [Boolean] message_ordering Whether message ordering has been
+        #   enabled. The value provided must match the value set on the Pub/Sub
+        #   service. See {#message_ordering?}. Optional.
+        #
+        #   When using a reference object an API call will be made to retrieve
+        #   the default message_ordering value for the subscription when this
+        #   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.
+        #   pull messages from the subscription. Default is 2. 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 `max_outstanding_messages` 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.)
+        #     * `:use_legacy_flow_control` [Boolean] Disables enforcing flow control settings at the Cloud PubSub
+        #       server and the less accurate method of only enforcing flow control at the client side is used instead.
+        #       Default is false.
+        #     * `: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.
         #
@@ -546,6 +983,7 @@ module Google
         #
         #   subscriber = sub.listen do |received_message|
         #     # process message
+        #     puts "Data: #{received_message.message.data}, published at #{received_message.message.published_at}"
         #     received_message.acknowledge!
         #   end
         #
@@ -553,7 +991,7 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         # @example Configuring to increase concurrent callbacks:
         #   require "google/cloud/pubsub"
@@ -571,14 +1009,55 @@ module Google
         #   # Start background threads that will call block passed to listen.
         #   subscriber.start
         #
-        def listen deadline: nil, streams: nil, inventory: nil, threads: {},
-                   &block
+        #   # Shut down the subscriber when ready to stop receiving messages.
+        #   subscriber.stop!
+        #
+        # @example Ordered messages are supported using ordering_key:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-ordered-topic-sub"
+        #   sub.message_ordering? #=> true
+        #
+        #   subscriber = sub.listen do |received_message|
+        #     # messsages with the same ordering_key are received
+        #     # in the order in which they were published.
+        #     received_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!
+        #
+        # @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!
+        #
+        def listen deadline: nil, message_ordering: nil, streams: nil, inventory: nil, threads: {}, &block
           ensure_service!
           deadline ||= self.deadline
+          message_ordering = message_ordering? if message_ordering.nil?
 
-          Subscriber.new name, block, deadline: deadline, streams: streams,
-                                      inventory: inventory, threads: threads,
-                                      service: service
+          Subscriber.new name, block, deadline: deadline, streams: streams, inventory: inventory,
+                                      message_ordering: message_ordering, threads: threads, service: service
         end
 
         ##
@@ -600,7 +1079,7 @@ module Google
         #   pubsub = Google::Cloud::PubSub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
-        #   received_messages = sub.pull
+        #   received_messages = sub.pull immediate: false
         #   sub.acknowledge received_messages
         #
         def acknowledge *messages
@@ -635,7 +1114,7 @@ module Google
         #   pubsub = Google::Cloud::PubSub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
-        #   received_messages = sub.pull
+        #   received_messages = sub.pull immediate: false
         #   sub.modify_ack_deadline 120, received_messages
         #
         def modify_ack_deadline new_deadline, *messages
@@ -656,14 +1135,19 @@ module Google
         # * Any messages published to the subscription's topic following the
         #   successful completion of the `create_snapshot` operation.
         #
-        # @param [String, nil] snapshot_name Name of the new snapshot. If the
-        #   name is not provided, the server will assign a random name
-        #   for this snapshot on the same project as the subscription. The
-        #   format is `projects/{project}/snapshots/{snap}`. The name must start
-        #   with a letter, and contain only letters ([A-Za-z]), numbers
-        #   ([0-9], dashes (-), underscores (_), periods (.), tildes (~), plus
-        #   (+) or percent signs (%). It must be between 3 and 255 characters in
-        #   length, and it must not start with "goog". Optional.
+        # @param [String, nil] snapshot_name Name of the new snapshot. Optional.
+        #   If the name is not provided, the server will assign a random name
+        #   for this snapshot on the same project as the subscription.
+        #   The value can be a simple snapshot ID (relative name), in which
+        #   case the current project ID will be supplied, or a fully-qualified
+        #   snapshot name in the form
+        #   `projects/{project_id}/snapshots/{snapshot_id}`.
+        #
+        #   The snapshot ID (relative name) must start with a letter, and
+        #   contain only letters (`[A-Za-z]`), numbers (`[0-9]`), dashes (`-`),
+        #   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 [Hash] labels A hash of user-provided labels associated with
         #   the snapshot. You can use these to organize and group your
         #   snapshots. Label keys and values can be no longer than 63
@@ -728,7 +1212,7 @@ module Google
         #
         #   snapshot = sub.create_snapshot
         #
-        #   received_messages = sub.pull
+        #   received_messages = sub.pull immediate: false
         #   sub.acknowledge received_messages
         #
         #   sub.seek snapshot
@@ -741,7 +1225,7 @@ module Google
         #
         #   time = Time.now
         #
-        #   received_messages = sub.pull
+        #   received_messages = sub.pull immediate: false
         #   sub.acknowledge received_messages
         #
         #   sub.seek time