google-cloud-pubsub 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00a75b823e392ec6afe50d693ae28a42833c2b40f06e8fa8311dff1cbafcc2df
-  data.tar.gz: d1caf14295648c05ac0f067832f1c7c8c51ee8638da47c49d3d5af6ad26ce23f
+  metadata.gz: 3ad1e392a28fae7f97e78f0e5a73fcccb4cef83462b7ff6caac53c4e450cbf91
+  data.tar.gz: 0d71eca6ba2b40ddb7d1855b2ea9bd4c75422aed74cc2f008cee1881fc850c43
 SHA512:
-  metadata.gz: 82745cfef6ebc3a5dae4bb44168660c6525ea2a2cac5d16f0087b8791d472a2d3eff5961627bf0ae7701a7f731715a21049b2da80ab551516c8e8da98aa31e6c
-  data.tar.gz: e9e2671fcf438f9cc5e7a5baa7cba1a1bb44fa5955bcad7a8ebaaffa111391457ea4d218a173c8f67b6a327e5f622406c20bd223c4799a5720008a5a99eda3c6
+  metadata.gz: 4ff13cb0796a1fff747785b078ead8f2c0e71d56cfabdaed4156b83eb5bb800c8e35fbc84a4e722f51df8602ff6ca8b81ddfbeac51ada0eb0c7029e5258467d8
+  data.tar.gz: '058a56e42f9f42366f709c86f1efe2cec8d1fe909ae2097ac2e7dc9a1e061376636bb7d109711ded9d84284c48b05bf739707b592e500ae8671fda76d22bbf88'

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Release History
 
+### 2.6.0 / 2021-04-19
+
+#### Features
+
+* Add ordering_key to Topic#publish
+  * Add ordering_key to BatchPublisher#publish
+
+#### Documentation
+
+* The immediate: false option is recommended to avoid adverse impacts on the performance of pull operations ([#11153](https://www.github.com/googleapis/google-cloud-ruby/issues/11153))
+* Update Subscription#pull docs and samples to recommend immediate: false
+
 ### 2.5.0 / 2021-04-01
 
 #### Features

data/CONTRIBUTING.md

@@ -119,15 +119,14 @@ If you alter an example's title, you may encounter breaking tests.
 ### Pub/Sub Acceptance Tests
 
 The Pub/Sub acceptance tests interact with the live service API. Follow the
-instructions in the {file:AUTHENTICATION.md Authentication guide} for enabling
+instructions in the {file:AUTHENTICATION.md Authentication Guide} for enabling
 the Pub/Sub API. Occasionally, some API features may not yet be generally
 available, making it difficult for some contributors to successfully run the
 entire acceptance test suite. However, please ensure that you do successfully
 run acceptance tests for any code areas covered by your pull request.
 
 To run the acceptance tests, first create and configure a project in the Google
-Developers Console, as described in the {file:AUTHENTICATION.md Authentication
-guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
+Developers Console, as described in the {file:AUTHENTICATION.md Authentication Guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
 the KEYFILE location on your system.
 
 Before you can run the Pub/Sub acceptance tests, you must first create indexes

data/OVERVIEW.md

@@ -205,13 +205,16 @@ sleep
 Messages also can be pulled directly in a one-time operation. (See
 {Google::Cloud::PubSub::Subscription#pull Subscription#pull})
 
+The `immediate: false` option is recommended to avoid adverse impacts on the
+performance of pull operations.
+
 ```ruby
 require "google/cloud/pubsub"
 
 pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
-received_messages = sub.pull
+received_messages = sub.pull immediate: false
 ```
 
 A maximum number of messages to pull can be specified:
@@ -222,7 +225,7 @@ require "google/cloud/pubsub"
 pubsub = Google::Cloud::PubSub.new
 
 sub = pubsub.subscription "my-topic-sub"
-received_messages = sub.pull max: 10
+received_messages = sub.pull immediate: false, max: 10
 ```
 
 ## Acknowledging a Message
@@ -263,7 +266,7 @@ require "google/cloud/pubsub"
 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
 ```
 
@@ -328,7 +331,7 @@ require "google/cloud/pubsub"
 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
 ```
 
@@ -474,7 +477,7 @@ sub = pubsub.subscription "my-topic-sub"
 
 snapshot = sub.create_snapshot
 
-received_messages = sub.pull
+received_messages = sub.pull immediate: false
 sub.acknowledge received_messages
 
 sub.seek snapshot
@@ -521,5 +524,5 @@ sub.topic.name #=> "projects/other-project-id/topics/other-topic"
 ## Additional information
 
 Google Cloud Pub/Sub can be configured to use an emulator or to enable gRPC's
-logging. To learn more, see the {file:EMULATOR.md Emulator guide} and
+logging. To learn more, see the {file:EMULATOR.md Emulator guide}} and
 {file:LOGGING.md Logging guide}.

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

@@ -13,6 +13,8 @@
 # limitations under the License.
 
 
+require "google/cloud/pubsub/convert"
+
 module Google
   module Cloud
     module PubSub
@@ -26,11 +28,12 @@ module Google
       #   pubsub = Google::Cloud::PubSub.new
       #
       #   topic = pubsub.topic "my-topic"
-      #   msgs = topic.publish do |t|
-      #     t.publish "task 1 completed", foo: :bar
-      #     t.publish "task 2 completed", foo: :baz
-      #     t.publish "task 3 completed", foo: :bif
+      #   msgs = topic.publish do |batch_publisher|
+      #     batch_publisher.publish "task 1 completed", foo: :bar
+      #     batch_publisher.publish "task 2 completed", foo: :baz
+      #     batch_publisher.publish "task 3 completed", foo: :bif
       #   end
+      #
       class BatchPublisher
         ##
         # @private The messages to publish
@@ -38,20 +41,40 @@ module Google
 
         ##
         # @private Create a new instance of the object.
-        def initialize data = nil, attributes = {}
+        def initialize data, attributes, ordering_key, extra_attrs
           @messages = []
           @mode = :batch
           return if data.nil?
           @mode = :single
-          publish data, attributes
+          publish data, attributes, ordering_key: ordering_key, **extra_attrs
         end
 
         ##
         # Add a message to the batch to be published to the topic.
         # All messages added to the batch will be published at once.
         # See {Google::Cloud::PubSub::Topic#publish}
-        def publish data, attributes = {}
-          @messages << create_pubsub_message(data, attributes)
+        #
+        # @param [String, File] data The message payload. This will be converted
+        #   to bytes encoded as ASCII-8BIT.
+        # @param [Hash] attributes Optional attributes for the message.
+        # @param [String] ordering_key Identifies related messages for which
+        #   publish order should be respected.
+        #
+        # @example Multiple messages can be sent at the same time using a block:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   topic = pubsub.topic "my-topic"
+        #   msgs = topic.publish do |batch_publisher|
+        #     batch_publisher.publish "task 1 completed", foo: :bar
+        #     batch_publisher.publish "task 2 completed", foo: :baz
+        #     batch_publisher.publish "task 3 completed", foo: :bif
+        #   end
+        #
+        def publish data, attributes = nil, ordering_key: nil, **extra_attrs
+          msg = Convert.pubsub_message data, attributes, ordering_key, extra_attrs
+          @messages << msg
         end
 
         ##
@@ -69,28 +92,6 @@ module Google
             msgs
           end
         end
-
-        protected
-
-        def create_pubsub_message data, attributes
-          attributes ||= {}
-          if data.is_a?(::Hash) && attributes.empty?
-            attributes = data
-            data = nil
-          end
-          # Convert IO-ish objects to strings
-          if data.respond_to?(:read) && data.respond_to?(:rewind)
-            data.rewind
-            data = data.read
-          end
-          # Convert data to encoded byte array to match the protobuf defn
-          data_bytes = String(data).dup.force_encoding(Encoding::ASCII_8BIT).freeze
-
-          # Convert attributes to strings to match the protobuf definition
-          attributes = Hash[attributes.map { |k, v| [String(k), String(v)] }]
-
-          Google::Cloud::PubSub::V1::PubsubMessage.new data: data_bytes, attributes: attributes
-        end
       end
     end
 

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

@@ -733,19 +733,28 @@ 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.
+        # 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.
@@ -755,31 +764,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
@@ -1010,7 +1012,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
@@ -1045,7 +1047,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
@@ -1143,7 +1145,7 @@ module Google
         #
         #   snapshot = sub.create_snapshot
         #
-        #   received_messages = sub.pull
+        #   received_messages = sub.pull immediate: false
         #   sub.acknowledge received_messages
         #
         #   sub.seek snapshot
@@ -1156,7 +1158,7 @@ module Google
         #
         #   time = Time.now
         #
-        #   received_messages = sub.pull
+        #   received_messages = sub.pull immediate: false
         #   sub.acknowledge received_messages
         #
         #   sub.seek time

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

@@ -588,6 +588,8 @@ module Google
         # @param [String, File] data The message payload. This will be converted
         #   to bytes encoded as ASCII-8BIT.
         # @param [Hash] attributes Optional attributes for the message.
+        # @param [String] ordering_key Identifies related messages for which
+        #   publish order should be respected.
         # @yield [batch] a block for publishing multiple messages in one
         #   request
         # @yieldparam [BatchPublisher] batch the topic batch publisher
@@ -636,10 +638,24 @@ module Google
         #     t.publish "task 3 completed", foo: :bif
         #   end
         #
-        def publish data = nil, attributes = {}
+        # @example Ordered messages are supported using ordering_key:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   topic = pubsub.topic "my-ordered-topic"
+        #
+        #   # Ensure that message ordering is enabled.
+        #   topic.enable_message_ordering!
+        #
+        #   # Publish an ordered message with an ordering key.
+        #   topic.publish "task completed",
+        #                 ordering_key: "task-key"
+        #
+        def publish data = nil, attributes = nil, ordering_key: nil, **extra_attrs, &block
           ensure_service!
-          batch = BatchPublisher.new data, attributes
-          yield batch if block_given?
+          batch = BatchPublisher.new data, attributes, ordering_key, extra_attrs
+          block&.call batch
           return nil if batch.messages.count.zero?
           publish_batch_messages batch
         end

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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-pubsub
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-04-01 00:00:00.000000000 Z
+date: 2021-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby