google-cloud-pubsub 2.0.0 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5faee5de29df83057422ad7029a047eb10e8408a9b4e87599d301bc1c907a06
-  data.tar.gz: bc9d9b75232d66b09b5d45310875fbbd734663cf226575e43656da47aa955204
+  metadata.gz: 3af82f9222001a7e9b8a4648b53370da523629e3950822ec70b2994c7ff1ab69
+  data.tar.gz: c65a361d505e5416be05189668fb62260b91eabb89be8fedc8b4928a9a0724dc
 SHA512:
-  metadata.gz: b59bc075932f2a592276a8e0472371a18a8cc6e835ccb6c36ece17f277528bf92813d978e06393cf384c54c282c8a04fa6ba1d2fcfab08214e3cb3a55d2724ac
-  data.tar.gz: 8a6fffc01ab630eaf960c3c87858f942fe6a0241cfdf024875d379f2a915be724ea209bcfdc07c7ab12a1299949785456c27f0725d6d4b4cac519749cbc6f1fc
+  metadata.gz: e0fd3399bed14e3ec636a352cefc9c03a34f76ad20adbd12c3c043bdebf23ea75c68b9cab5e0fe0e259911b7a466f8b0e4d0b138ea9cd3244653d13749b38920
+  data.tar.gz: 91243885834f4cb5c3423bc8f6e75383d95cbdb5b09b6a4bd409b701a6c0433838882188a28cf150302cd4ea3fa8c48afc669f7590d9578d67858b246ad77fc7

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Release History
 
+### 2.3.1 / 2021-01-13
+
+#### Bug Fixes
+
+* Update Subscription#retry_policy=
+  * Remove conditional RPC to fetch full resource before update.
+
+### 2.3.0 / 2020-11-18
+
+#### Features
+
+* Add inventory.use_legacy_flow_control to listen options
+  * Add inventory.use_legacy_flow_control to Subscription#listen options
+  * Add Subscriber#use_legacy_flow_control?
+
+#### Documentation
+
+* Remove EXPERIMENTAL label from RetryPolicy docs
+
+### 2.2.0 / 2020-11-11
+
+#### Features
+
+* Add Subscription#remove_dead_letter_policy
+
+### 2.1.1 / 2020-10-26
+
+#### Documentation
+
+* Update deprecated attribute name limit to max_outstanding_messages
+
+### 2.1.0 / 2020-09-17
+
+#### Features
+
+* quota_project can be set via library configuration ([#7630](https://www.github.com/googleapis/google-cloud-ruby/issues/7630))
+* Add push_config (PushConfig) param to Topic#subscribe
+  * Make PushConfig constructor public.
+
+#### Documentation
+
+* Update sample code for on_error, at_exit, and concurrency tuning
+
 ### 2.0.0 / 2020-08-06
 
 This is a major update that removes the "low-level" client interface code, and

data/CONTRIBUTING.md

@@ -45,7 +45,7 @@ there is a small amount of setup:
 
    ```sh
    $ cd google-cloud-pubsub/
-   $ bundle exec rake bundleupdate
+   $ bundle install
    ```
 
 ## Console

data/OVERVIEW.md

@@ -142,7 +142,7 @@ topic.publish_async "task completed" do |result|
   end
 end
 
-topic.async_publisher.stop.wait!
+topic.async_publisher.stop!
 ```
 
 Or multiple messages can be published in batches at the same time by passing a
@@ -174,16 +174,32 @@ pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
 
-subscriber = sub.listen do |received_message|
+# Create a subscriber to listen for available messages.
+# By default, this block will be called on 8 concurrent threads
+# but this can be tuned with the `threads` option.
+# The `streams` and `inventory` parameters allow further tuning.
+subscriber = sub.listen threads: { callback: 16 } do |received_message|
   # process message
+  puts "Data: #{received_message.message.data}, published at #{received_message.message.published_at}"
   received_message.acknowledge!
 end
 
+# Handle exceptions from listener
+subscriber.on_error do |exception|
+  puts "Exception: #{exception.class} #{exception.message}"
+end
+
+# Gracefully shut down the subscriber on program exit, blocking until
+# all received messages have been processed or 10 seconds have passed
+at_exit do
+  subscriber.stop!(10)
+end
+
 # Start background threads that will call the block passed to listen.
 subscriber.start
 
-# Shut down the subscriber when ready to stop receiving messages.
-subscriber.stop.wait!
+# Block, letting processing threads continue in the background
+sleep
 ```
 
 Messages also can be pulled directly in a one-time operation. (See
@@ -235,7 +251,7 @@ end
 subscriber.start
 
 # Shut down the subscriber when ready to stop receiving messages.
-subscriber.stop.wait!
+subscriber.stop!
 ```
 
 Or, multiple messages can be acknowledged in a single API call: (See
@@ -277,7 +293,7 @@ end
 subscriber.start
 
 # Shut down the subscriber when ready to stop receiving messages.
-subscriber.stop.wait!
+subscriber.stop!
 ```
 
 The message can also be made available for immediate redelivery:
@@ -299,7 +315,7 @@ end
 subscriber.start
 
 # Shut down the subscriber when ready to stop receiving messages.
-subscriber.stop.wait!
+subscriber.stop!
 ```
 
 Multiple messages can be delayed or made available for immediate redelivery:
@@ -353,7 +369,7 @@ topic.publish_async "task completed",
                     ordering_key: "task-key"
 
 # Shut down the publisher when ready to stop publishing messages.
-topic.async_publisher.stop.wait!
+topic.async_publisher.stop!
 ```
 
 ### Handling errors with Ordered Keys
@@ -395,7 +411,7 @@ end
 subscriber.start
 
 # Shut down the subscriber when ready to stop receiving messages.
-subscriber.stop.wait!
+subscriber.stop!
 ```
 
 ## Minimizing API calls before receiving and acknowledging messages
@@ -425,7 +441,7 @@ end
 subscriber.start
 
 # Shut down the subscriber when ready to stop receiving messages.
-subscriber.stop.wait!
+subscriber.stop!
 ```
 
 Skipping API calls may be used to avoid `Google::Cloud::PermissionDeniedError`
@@ -464,54 +480,6 @@ sub.acknowledge received_messages
 sub.seek snapshot
 ```
 
-## Listening for Messages
-
-A subscriber object can be created using `listen`, which streams messages from
-the backend and processes them as they are received. (See
-{Google::Cloud::PubSub::Subscription#listen Subscription#listen} and
-{Google::Cloud::PubSub::Subscriber Subscriber})
-
-```ruby
-require "google/cloud/pubsub"
-
-pubsub = Google::Cloud::PubSub.new
-
-sub = pubsub.subscription "my-topic-sub"
-
-subscriber = sub.listen do |received_message|
-  # process message
-  received_message.acknowledge!
-end
-
-# Start background threads that will call the block passed to listen.
-subscriber.start
-
-# Shut down the subscriber when ready to stop receiving messages.
-subscriber.stop.wait!
-```
-
-The subscriber object can be configured to control the number of concurrent
-streams to open, the number of received messages to be collected, and the number
-of threads each stream opens for concurrent calls made to handle the received
-messages.
-
-```ruby
-require "google/cloud/pubsub"
-
-pubsub = Google::Cloud::PubSub.new
-
-sub = pubsub.subscription "my-topic-sub"
-
-subscriber = sub.listen threads: { callback: 16 } do |received_message|
-  # store the message somewhere before acknowledging
-  store_in_backend received_message.data # takes a few seconds
-  received_message.acknowledge!
-end
-
-# Start background threads that will call the block passed to listen.
-subscriber.start
-```
-
 ## Working Across Projects
 
 All calls to the Pub/Sub service use the same project and credentials provided

data/lib/google-cloud-pubsub.rb

@@ -132,6 +132,7 @@ Google::Cloud.configure.add_config! :pubsub do |config|
   config.add_field! :credentials, default_creds, match: [String, Hash, Google::Auth::Credentials], allow_nil: true
   config.add_alias! :keyfile, :credentials
   config.add_field! :scope, default_scopes, match: [String, Array]
+  config.add_field! :quota_project, nil, match: String
   config.add_field! :timeout, nil, match: Integer
   config.add_field! :emulator_host, default_emulator, match: String, allow_nil: true
   config.add_field! :on_error, nil, match: Proc

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

@@ -42,7 +42,7 @@ module Google
       #     end
       #   end
       #
-      #   topic.async_publisher.stop.wait!
+      #   topic.async_publisher.stop!
       #
       # @attr_reader [String] topic_name The name of the topic the messages are published to. In the form of
       #   "/projects/project-identifier/topics/topic-name".

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

@@ -50,7 +50,7 @@ module Google
       #   subscriber.start
       #
       #   # Shut down the subscriber when ready to stop receiving messages.
-      #   subscriber.stop.wait!
+      #   subscriber.stop!
       #
       class Message
         ##

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

@@ -141,7 +141,7 @@ module Google
         #     end
         #   end
         #
-        #   topic.async_publisher.stop.wait!
+        #   topic.async_publisher.stop!
         #
         def topic topic_name, project: nil, skip_lookup: nil, async: nil
           ensure_service!

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

@@ -39,7 +39,7 @@ module Google
       #   subscriber.start
       #
       #   # Shut down the subscriber when ready to stop receiving messages.
-      #   subscriber.stop.wait!
+      #   subscriber.stop!
       #
       class ReceivedMessage
         ##
@@ -177,7 +177,7 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         def acknowledge!
           ensure_subscription!
@@ -214,7 +214,7 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         def modify_ack_deadline! new_deadline
           ensure_subscription!
@@ -244,7 +244,7 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         def reject!
           modify_ack_deadline! 0

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

@@ -31,9 +31,6 @@ module Google
       # Retry Policy is implemented on a best effort basis. At times, the delay between consecutive deliveries may not
       # match the configuration. That is, delay can be more or less than configured backoff.
       #
-      # **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.
-      #
       # @attr [Numeric] minimum_backoff The minimum delay between consecutive deliveries of a given message. Value
       #   should be between 0 and 600 seconds. The default value is 10 seconds.
       # @attr [Numeric] maximum_backoff The maximum delay between consecutive deliveries of a given message. Value

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

@@ -175,15 +175,10 @@ module Google
         ##
         # Creates a subscription on a given topic for a given subscriber.
         def create_subscription topic, subscription_name, options = {}
-          push_config = if options[:endpoint]
-                          Google::Cloud::PubSub::V1::PushConfig.new \
-                            push_endpoint: options[:endpoint],
-                            attributes:    (options[:attributes] || {}).to_h
-                        end
           subscriber.create_subscription \
             name:                       subscription_path(subscription_name, options),
             topic:                      topic_path(topic),
-            push_config:                push_config,
+            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]),

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

@@ -41,7 +41,7 @@ module Google
       #   subscriber.start
       #
       #   # Shut down the subscriber when ready to stop receiving messages.
-      #   subscriber.stop.wait!
+      #   subscriber.stop!
       #
       # @attr_reader [String] subscription_name The name of the subscription the
       #   messages are pulled from.
@@ -240,7 +240,7 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         def on_error &block
           synchronize do
@@ -276,7 +276,7 @@ module Google
         #   subscriber.last_error #=> nil
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         def last_error
           synchronize { @last_error }
@@ -306,6 +306,17 @@ module Google
         # @deprecated Use {#max_outstanding_bytes}.
         alias inventory_bytesize max_outstanding_bytes
 
+        ##
+        # Whether to enforce flow control at the client side only or to enforce it at both the client and
+        # the server. For more details about flow control see https://cloud.google.com/pubsub/docs/pull#config.
+        #
+        # @return [Boolean] `true` when only client side flow control is enforced, `false` when both client and
+        # server side flow control are enforced.
+        #
+        def use_legacy_flow_control?
+          @inventory[:use_legacy_flow_control]
+        end
+
         ##
         # The number of seconds that received messages can be held awaiting processing. Default is 3,600 (1 hour).
         #
@@ -334,7 +345,8 @@ module Google
             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]
+            max_duration_per_lease_extension: @inventory[:max_duration_per_lease_extension],
+            use_legacy_flow_control:          @inventory[:use_legacy_flow_control]
           }
         end
 
@@ -377,6 +389,7 @@ module Google
           @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)
+          @inventory[:use_legacy_flow_control] = @inventory[:use_legacy_flow_control] || false
         end
 
         def default_error_callbacks

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

@@ -30,15 +30,18 @@ module Google
 
           include MonitorMixin
 
-          attr_reader :stream, :limit, :bytesize, :extension, :max_duration_per_lease_extension
+          attr_reader :stream, :limit, :bytesize, :extension, :max_duration_per_lease_extension,
+                      :use_legacy_flow_control
 
-          def initialize stream, limit:, bytesize:, extension:, max_duration_per_lease_extension:
+          def initialize stream, limit:, bytesize:, extension:, max_duration_per_lease_extension:,
+                         use_legacy_flow_control:
             super()
             @stream = stream
             @limit = limit
             @bytesize = bytesize
             @extension = extension
             @max_duration_per_lease_extension = max_duration_per_lease_extension
+            @use_legacy_flow_control = use_legacy_flow_control
             @inventory = {}
             @wait_cond = new_cond
           end

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

@@ -363,8 +363,8 @@ module Google
               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
+              req.max_outstanding_messages = @inventory.use_legacy_flow_control ? 0 : @inventory.limit
+              req.max_outstanding_bytes = @inventory.use_legacy_flow_control ? 0 : @inventory.bytesize
             end
           end
 

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

@@ -43,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.
@@ -323,7 +330,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 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.
@@ -358,6 +365,9 @@ module Google
         # `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
@@ -370,8 +380,8 @@ module Google
         # 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}.
+        # 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?}.
         #
@@ -402,7 +412,11 @@ module Google
         # 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}.
+        # 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.
@@ -434,14 +448,15 @@ module Google
         # 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.
+        # 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=} and {#dead_letter_topic}.
+        # 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 value when called on a reference object. See {#reference?}.
+        # 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. If this
-        #   value is 0, a default value of 5 is used.
+        # @return [Integer, nil] A value between `5` and `100`, or `nil` if no dead letter policy is configured.
         #
         # @example
         #   require "google/cloud/pubsub"
@@ -468,10 +483,15 @@ module Google
         #
         # 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}.
+        # Makes an API call to retrieve the dead_letter_policy when called on a reference object. See {#reference?}.
         #
-        # @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.
+        # 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"
@@ -496,14 +516,48 @@ module Google
           @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.
         #
-        # **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.
+        # 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`.
         #
@@ -531,9 +585,6 @@ module Google
         # 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
@@ -549,10 +600,11 @@ module Google
         #   sub.retry_policy.maximum_backoff #=> 300
         #
         def retry_policy= new_retry_policy
-          ensure_grpc!
+          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
 
         ##
@@ -584,7 +636,7 @@ module Google
         #
         # See {Topic#subscribe} and {#detach}.
         #
-        # Makes an API call to retrieve the value when called on a
+        # Makes an API call to retrieve the detached value when called on a
         # reference object. See {#reference?}.
         #
         # @return [Boolean]
@@ -816,7 +868,8 @@ module Google
         # @param [Integer] streams The number of concurrent streams to open to
         #   pull messages from the subscription. Default is 4. 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.
+        #   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:
         #
@@ -824,6 +877,9 @@ module Google
         #       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
@@ -856,6 +912,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
         #
@@ -863,7 +920,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"
@@ -882,7 +939,7 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         # @example Ordered messages are supported using ordering_key:
         #   require "google/cloud/pubsub"
@@ -902,7 +959,7 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         # @example Set the maximum amount of time before redelivery if the subscriber fails to extend the deadline:
         #   require "google/cloud/pubsub"
@@ -921,7 +978,7 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
         def listen deadline: nil, message_ordering: nil, streams: nil, inventory: nil, threads: {}, &block
           ensure_service!

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

@@ -22,7 +22,18 @@ module Google
         ##
         # Configuration for a push delivery endpoint.
         #
-        # @example
+        # @example Create a push config:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   push_config = Google::Cloud::PubSub::Subscription::PushConfig.new endpoint: "http://example.net/callback"
+        #   push_config.set_oidc_token "service-account@example.net", "audience-header-value"
+        #
+        #   sub = topic.subscribe "my-subscription", push_config: push_config
+        #
+        # @example Read a push config:
         #   require "google/cloud/pubsub"
         #
         #   pubsub = Google::Cloud::PubSub.new
@@ -32,7 +43,7 @@ module Google
         #   sub.push_config.authentication.email #=> "user@example.com"
         #   sub.push_config.authentication.audience #=> "client-12345"
         #
-        # @example Update the push configuration by passing a block:
+        # @example Update a push config:
         #   require "google/cloud/pubsub"
         #
         #   pubsub = Google::Cloud::PubSub.new
@@ -45,14 +56,31 @@ module Google
         #
         class PushConfig
           ##
-          # @private
-          def initialize
+          # Creates a new push configuration.
+          #
+          # @param [String] endpoint A URL locating the endpoint to which messages should be pushed. For
+          #   example, a Webhook endpoint might use `https://example.com/push`.
+          # @param [String] email The service account email to be used for generating the OIDC token.
+          #   The caller must have the `iam.serviceAccounts.actAs` permission for the service account.
+          # @param [String] audience The audience to be used when generating OIDC token. The audience claim identifies
+          #   the recipients that the JWT is intended for. The audience value is a single case-sensitive string. Having
+          #   multiple values (array) for the audience field is not supported. More info about the OIDC JWT token
+          #   audience here: https://tools.ietf.org/html/rfc7519#section-4.1.3 Note: if not specified, the `endpoint`
+          #   URL will be used.
+          #
+          def initialize endpoint: nil, email: nil, audience: nil
             @grpc = Google::Cloud::PubSub::V1::PushConfig.new
+
+            self.endpoint = endpoint unless endpoint.nil?
+
+            raise ArgumentError, "audience provided without email. Authentication is invalid" if audience && !email
+
+            set_oidc_token email, audience if email
           end
 
           ##
-          # A URL locating the endpoint to which messages should be pushed. For
-          # example, a Webhook endpoint might use `https://example.com/push`.
+          # A URL locating the endpoint to which messages should be pushed. For example, a Webhook endpoint might use
+          # `https://example.com/push`.
           #
           # @return [String]
           def endpoint
@@ -60,9 +88,8 @@ module Google
           end
 
           ##
-          # Sets the URL locating the endpoint to which messages should be
-          # pushed. For example, a Webhook endpoint might use
-          # `https://example.com/push`.
+          # Sets the URL locating the endpoint to which messages should be pushed. For example, a Webhook endpoint might
+          # use `https://example.com/push`.
           #
           # @param [String, nil] new_endpoint New URL value
           def endpoint= new_endpoint
@@ -70,8 +97,7 @@ module Google
           end
 
           ##
-          # The authentication method used by push endpoints to verify the
-          # source of push requests.
+          # The authentication method used by push endpoints to verify the source of push requests.
           #
           # @return [OidcToken, nil] An OIDC JWT token if specified, `nil`
           #   otherwise.
@@ -82,8 +108,7 @@ module Google
           end
 
           ##
-          # Sets the authentication method used by push endpoints to verify the
-          # source of push requests.
+          # Sets the authentication method used by push endpoints to verify the source of push requests.
           #
           # @param [OidcToken, nil] new_auth An authentication value.
           def authentication= new_auth
@@ -118,13 +143,12 @@ module Google
           end
 
           ##
-          # The format of the pushed message. This attribute indicates the
-          # version of the data expected by the endpoint. This controls the
-          # shape of the pushed message (i.e., its fields and metadata). The
-          # endpoint version is based on the version of the Pub/Sub API.
+          # The format of the pushed message. This attribute indicates the version of the data expected by the endpoint.
+          # This controls the shape of the pushed message (i.e., its fields and metadata). The endpoint version is based
+          # on the version of the Pub/Sub API.
           #
-          # If not present during the Subscription creation, it will default to
-          # the version of the API used to make such call.
+          # If not present during the Subscription creation, it will default to the version of the API used to make such
+          # call.
           #
           # The possible values for this attribute are:
           #
@@ -182,7 +206,8 @@ module Google
             end
 
             ##
-            # Service account email to be used for generating the OIDC token.
+            # The service account email to be used for generating the OIDC token. The caller must have the
+            # `iam.serviceAccounts.actAs` permission for the service account.
             #
             # @return [String]
             def email
@@ -190,7 +215,8 @@ module Google
             end
 
             ##
-            # Service account email to be used for generating the OIDC token.
+            # Sets the service account email to be used for generating the OIDC token. The caller must have the
+            # `iam.serviceAccounts.actAs` permission for the service account.
             #
             # @param [String] new_email New service account email value.
             def email= new_email
@@ -198,15 +224,10 @@ module Google
             end
 
             ##
-            # Audience to be used when generating OIDC token. The audience claim
-            # identifies the recipients that the JWT is intended for. The
-            # audience value is a single case-sensitive string.
-            #
-            # Having multiple values (array) for the audience field is not
-            # supported.
-            #
-            # More info about the OIDC JWT token audience here:
-            # https://tools.ietf.org/html/rfc7519#section-4.1.3
+            # The audience to be used when generating OIDC token. The audience claim identifies the recipients that
+            # the JWT is intended for. The audience value is a single case-sensitive string. Having multiple values
+            # (array) for the audience field is not supported. More info about the OIDC JWT token audience here:
+            # https://tools.ietf.org/html/rfc7519#section-4.1.3 Note: if not specified, the `endpoint` URL will be used.
             #
             # @return [String]
             def audience
@@ -214,7 +235,10 @@ module Google
             end
 
             ##
-            # Sets the audience to be used when generating OIDC token.
+            # Sets the audience to be used when generating OIDC token. The audience claim identifies the recipients that
+            # the JWT is intended for. The audience value is a single case-sensitive string. Having multiple values
+            # (array) for the audience field is not supported. More info about the OIDC JWT token audience here:
+            # https://tools.ietf.org/html/rfc7519#section-4.1.3 Note: if not specified, the `endpoint` URL will be used.
             #
             # @param [String] new_audience New audience value.
             def audience= new_audience

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

@@ -78,7 +78,7 @@ module Google
         #     end
         #   end
         #
-        #   topic.async_publisher.stop.wait!
+        #   topic.async_publisher.stop!
         #
         def async_publisher
           @async_publisher
@@ -275,7 +275,10 @@ module Google
         #   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
-        #   should be pushed.
+        #   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
         #   the subscription. You can use these to organize and group your
         #   subscriptions. Label keys and values can be no longer than 63
@@ -306,9 +309,6 @@ module Google
         #   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 [Google::Cloud::PubSub::Subscription]
         #
         # @example
@@ -320,15 +320,25 @@ module Google
         #   sub = topic.subscribe "my-topic-sub"
         #   sub.name # => "my-topic-sub"
         #
-        # @example Wait 2 minutes for acknowledgement and push all to endpoint:
+        # @example Wait 2 minutes for acknowledgement:
         #   require "google/cloud/pubsub"
         #
         #   pubsub = Google::Cloud::PubSub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   sub = topic.subscribe "my-topic-sub",
-        #                         deadline: 120,
-        #                         endpoint: "https://example.com/push"
+        #                         deadline: 120
+        #
+        # @example Configure a push endpoint:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   push_config = Google::Cloud::PubSub::Subscription::PushConfig.new endpoint: "http://example.net/callback"
+        #   push_config.set_oidc_token "service-account@example.net", "audience-header-value"
+        #
+        #   sub = topic.subscribe "my-subscription", push_config: push_config
         #
         # @example Configure a Dead Letter Queues policy:
         #   require "google/cloud/pubsub"
@@ -361,19 +371,40 @@ 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, labels: nil,
-                      message_ordering: nil, filter: nil, dead_letter_topic: nil,
-                      dead_letter_max_delivery_attempts: nil, retry_policy: nil
+        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
           ensure_service!
-          options = { deadline: deadline, retain_acked: retain_acked, retention: retention, endpoint: endpoint,
-                      labels: labels, message_ordering: message_ordering, filter: filter,
-                      dead_letter_max_delivery_attempts: dead_letter_max_delivery_attempts }
+          if push_config && 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
+          }
 
           options[:dead_letter_topic_name] = dead_letter_topic.name if 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
           grpc = service.create_subscription name, subscription_name, options
           Subscription.from_grpc grpc, service
@@ -590,7 +621,7 @@ module Google
         #   end
         #
         #   # Shut down the publisher when ready to stop publishing messages.
-        #   topic.async_publisher.stop.wait!
+        #   topic.async_publisher.stop!
         #
         # @example A message can be published using a File object:
         #   require "google/cloud/pubsub"
@@ -602,7 +633,7 @@ module Google
         #   topic.publish_async file
         #
         #   # Shut down the publisher when ready to stop publishing messages.
-        #   topic.async_publisher.stop.wait!
+        #   topic.async_publisher.stop!
         #
         # @example Additionally, a message can be published with attributes:
         #   require "google/cloud/pubsub"
@@ -614,7 +645,7 @@ module Google
         #                       foo: :bar, this: :that
         #
         #   # Shut down the publisher when ready to stop publishing messages.
-        #   topic.async_publisher.stop.wait!
+        #   topic.async_publisher.stop!
         #
         # @example Ordered messages are supported using ordering_key:
         #   require "google/cloud/pubsub"
@@ -631,7 +662,7 @@ module Google
         #                       ordering_key: "task-key"
         #
         #   # Shut down the publisher when ready to stop publishing messages.
-        #   topic.async_publisher.stop.wait!
+        #   topic.async_publisher.stop!
         #
         def publish_async data = nil, attributes = nil, ordering_key: nil, **extra_attrs, &callback
           ensure_service!

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module PubSub
-      VERSION = "2.0.0".freeze
+      VERSION = "2.3.1".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.0.0
+  version: 2.3.1
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-06 00:00:00.000000000 Z
+date: 2021-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -259,7 +259,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.3
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Pub/Sub