google-cloud-pubsub 2.5.0 → 2.6.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 00a75b823e392ec6afe50d693ae28a42833c2b40f06e8fa8311dff1cbafcc2df
4
- data.tar.gz: d1caf14295648c05ac0f067832f1c7c8c51ee8638da47c49d3d5af6ad26ce23f
3
+ metadata.gz: 3ad1e392a28fae7f97e78f0e5a73fcccb4cef83462b7ff6caac53c4e450cbf91
4
+ data.tar.gz: 0d71eca6ba2b40ddb7d1855b2ea9bd4c75422aed74cc2f008cee1881fc850c43
5
5
  SHA512:
6
- metadata.gz: 82745cfef6ebc3a5dae4bb44168660c6525ea2a2cac5d16f0087b8791d472a2d3eff5961627bf0ae7701a7f731715a21049b2da80ab551516c8e8da98aa31e6c
7
- data.tar.gz: e9e2671fcf438f9cc5e7a5baa7cba1a1bb44fa5955bcad7a8ebaaffa111391457ea4d218a173c8f67b6a327e5f622406c20bd223c4799a5720008a5a99eda3c6
6
+ metadata.gz: 4ff13cb0796a1fff747785b078ead8f2c0e71d56cfabdaed4156b83eb5bb800c8e35fbc84a4e722f51df8602ff6ca8b81ddfbeac51ada0eb0c7029e5258467d8
7
+ data.tar.gz: '058a56e42f9f42366f709c86f1efe2cec8d1fe909ae2097ac2e7dc9a1e061376636bb7d109711ded9d84284c48b05bf739707b592e500ae8671fda76d22bbf88'
data/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Release History
2
2
 
3
+ ### 2.6.0 / 2021-04-19
4
+
5
+ #### Features
6
+
7
+ * Add ordering_key to Topic#publish
8
+ * Add ordering_key to BatchPublisher#publish
9
+
10
+ #### Documentation
11
+
12
+ * 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))
13
+ * Update Subscription#pull docs and samples to recommend immediate: false
14
+
3
15
  ### 2.5.0 / 2021-04-01
4
16
 
5
17
  #### Features
data/CONTRIBUTING.md CHANGED
@@ -119,15 +119,14 @@ If you alter an example's title, you may encounter breaking tests.
119
119
  ### Pub/Sub Acceptance Tests
120
120
 
121
121
  The Pub/Sub acceptance tests interact with the live service API. Follow the
122
- instructions in the {file:AUTHENTICATION.md Authentication guide} for enabling
122
+ instructions in the {file:AUTHENTICATION.md Authentication Guide} for enabling
123
123
  the Pub/Sub API. Occasionally, some API features may not yet be generally
124
124
  available, making it difficult for some contributors to successfully run the
125
125
  entire acceptance test suite. However, please ensure that you do successfully
126
126
  run acceptance tests for any code areas covered by your pull request.
127
127
 
128
128
  To run the acceptance tests, first create and configure a project in the Google
129
- Developers Console, as described in the {file:AUTHENTICATION.md Authentication
130
- guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
129
+ 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
131
130
  the KEYFILE location on your system.
132
131
 
133
132
  Before you can run the Pub/Sub acceptance tests, you must first create indexes
data/OVERVIEW.md CHANGED
@@ -205,13 +205,16 @@ sleep
205
205
  Messages also can be pulled directly in a one-time operation. (See
206
206
  {Google::Cloud::PubSub::Subscription#pull Subscription#pull})
207
207
 
208
+ The `immediate: false` option is recommended to avoid adverse impacts on the
209
+ performance of pull operations.
210
+
208
211
  ```ruby
209
212
  require "google/cloud/pubsub"
210
213
 
211
214
  pubsub = Google::Cloud::PubSub.new
212
215
 
213
216
  sub = pubsub.subscription "my-topic-sub"
214
- received_messages = sub.pull
217
+ received_messages = sub.pull immediate: false
215
218
  ```
216
219
 
217
220
  A maximum number of messages to pull can be specified:
@@ -222,7 +225,7 @@ require "google/cloud/pubsub"
222
225
  pubsub = Google::Cloud::PubSub.new
223
226
 
224
227
  sub = pubsub.subscription "my-topic-sub"
225
- received_messages = sub.pull max: 10
228
+ received_messages = sub.pull immediate: false, max: 10
226
229
  ```
227
230
 
228
231
  ## Acknowledging a Message
@@ -263,7 +266,7 @@ require "google/cloud/pubsub"
263
266
  pubsub = Google::Cloud::PubSub.new
264
267
 
265
268
  sub = pubsub.subscription "my-topic-sub"
266
- received_messages = sub.pull
269
+ received_messages = sub.pull immediate: false
267
270
  sub.acknowledge received_messages
268
271
  ```
269
272
 
@@ -328,7 +331,7 @@ require "google/cloud/pubsub"
328
331
  pubsub = Google::Cloud::PubSub.new
329
332
 
330
333
  sub = pubsub.subscription "my-topic-sub"
331
- received_messages = sub.pull
334
+ received_messages = sub.pull immediate: false
332
335
  sub.modify_ack_deadline 120, received_messages
333
336
  ```
334
337
 
@@ -474,7 +477,7 @@ sub = pubsub.subscription "my-topic-sub"
474
477
 
475
478
  snapshot = sub.create_snapshot
476
479
 
477
- received_messages = sub.pull
480
+ received_messages = sub.pull immediate: false
478
481
  sub.acknowledge received_messages
479
482
 
480
483
  sub.seek snapshot
@@ -521,5 +524,5 @@ sub.topic.name #=> "projects/other-project-id/topics/other-topic"
521
524
  ## Additional information
522
525
 
523
526
  Google Cloud Pub/Sub can be configured to use an emulator or to enable gRPC's
524
- logging. To learn more, see the {file:EMULATOR.md Emulator guide} and
527
+ logging. To learn more, see the {file:EMULATOR.md Emulator guide}} and
525
528
  {file:LOGGING.md Logging guide}.
@@ -13,6 +13,8 @@
13
13
  # limitations under the License.
14
14
 
15
15
 
16
+ require "google/cloud/pubsub/convert"
17
+
16
18
  module Google
17
19
  module Cloud
18
20
  module PubSub
@@ -26,11 +28,12 @@ module Google
26
28
  # pubsub = Google::Cloud::PubSub.new
27
29
  #
28
30
  # topic = pubsub.topic "my-topic"
29
- # msgs = topic.publish do |t|
30
- # t.publish "task 1 completed", foo: :bar
31
- # t.publish "task 2 completed", foo: :baz
32
- # t.publish "task 3 completed", foo: :bif
31
+ # msgs = topic.publish do |batch_publisher|
32
+ # batch_publisher.publish "task 1 completed", foo: :bar
33
+ # batch_publisher.publish "task 2 completed", foo: :baz
34
+ # batch_publisher.publish "task 3 completed", foo: :bif
33
35
  # end
36
+ #
34
37
  class BatchPublisher
35
38
  ##
36
39
  # @private The messages to publish
@@ -38,20 +41,40 @@ module Google
38
41
 
39
42
  ##
40
43
  # @private Create a new instance of the object.
41
- def initialize data = nil, attributes = {}
44
+ def initialize data, attributes, ordering_key, extra_attrs
42
45
  @messages = []
43
46
  @mode = :batch
44
47
  return if data.nil?
45
48
  @mode = :single
46
- publish data, attributes
49
+ publish data, attributes, ordering_key: ordering_key, **extra_attrs
47
50
  end
48
51
 
49
52
  ##
50
53
  # Add a message to the batch to be published to the topic.
51
54
  # All messages added to the batch will be published at once.
52
55
  # See {Google::Cloud::PubSub::Topic#publish}
53
- def publish data, attributes = {}
54
- @messages << create_pubsub_message(data, attributes)
56
+ #
57
+ # @param [String, File] data The message payload. This will be converted
58
+ # to bytes encoded as ASCII-8BIT.
59
+ # @param [Hash] attributes Optional attributes for the message.
60
+ # @param [String] ordering_key Identifies related messages for which
61
+ # publish order should be respected.
62
+ #
63
+ # @example Multiple messages can be sent at the same time using a block:
64
+ # require "google/cloud/pubsub"
65
+ #
66
+ # pubsub = Google::Cloud::PubSub.new
67
+ #
68
+ # topic = pubsub.topic "my-topic"
69
+ # msgs = topic.publish do |batch_publisher|
70
+ # batch_publisher.publish "task 1 completed", foo: :bar
71
+ # batch_publisher.publish "task 2 completed", foo: :baz
72
+ # batch_publisher.publish "task 3 completed", foo: :bif
73
+ # end
74
+ #
75
+ def publish data, attributes = nil, ordering_key: nil, **extra_attrs
76
+ msg = Convert.pubsub_message data, attributes, ordering_key, extra_attrs
77
+ @messages << msg
55
78
  end
56
79
 
57
80
  ##
@@ -69,28 +92,6 @@ module Google
69
92
  msgs
70
93
  end
71
94
  end
72
-
73
- protected
74
-
75
- def create_pubsub_message data, attributes
76
- attributes ||= {}
77
- if data.is_a?(::Hash) && attributes.empty?
78
- attributes = data
79
- data = nil
80
- end
81
- # Convert IO-ish objects to strings
82
- if data.respond_to?(:read) && data.respond_to?(:rewind)
83
- data.rewind
84
- data = data.read
85
- end
86
- # Convert data to encoded byte array to match the protobuf defn
87
- data_bytes = String(data).dup.force_encoding(Encoding::ASCII_8BIT).freeze
88
-
89
- # Convert attributes to strings to match the protobuf definition
90
- attributes = Hash[attributes.map { |k, v| [String(k), String(v)] }]
91
-
92
- Google::Cloud::PubSub::V1::PubsubMessage.new data: data_bytes, attributes: attributes
93
- end
94
95
  end
95
96
  end
96
97
 
@@ -733,19 +733,28 @@ module Google
733
733
  end
734
734
 
735
735
  ##
736
- # Pulls messages from the server. Returns an empty list if there are no
737
- # messages available in the backlog. Raises an ApiError with status
738
- # `UNAVAILABLE` if there are too many concurrent pull requests pending
739
- # for the given subscription.
736
+ # Pulls messages from the server, blocking until messages are available
737
+ # when called with the `immediate: false` option, which is recommended
738
+ # to avoid adverse impacts on the performance of pull operations.
739
+ #
740
+ # Raises an API error with status `UNAVAILABLE` if there are too many
741
+ # concurrent pull requests pending for the given subscription.
740
742
  #
741
743
  # See also {#listen} for the preferred way to process messages as they
742
744
  # become available.
743
745
  #
744
- # @param [Boolean] immediate When `true` the system will respond
745
- # immediately even if it is not able to return messages. When `false`
746
- # the system is allowed to wait until it can return least one message.
747
- # No messages are returned when a request times out. The default value
748
- # is `true`.
746
+ # @param [Boolean] immediate Whether to return immediately or block until
747
+ # messages are available.
748
+ #
749
+ # **Warning:** The default value of this field is `true`. However, sending
750
+ # `true` is discouraged because it adversely impacts the performance of
751
+ # pull operations. We recommend that users always explicitly set this field
752
+ # to `false`.
753
+ #
754
+ # If this field set to `true`, the system will respond immediately
755
+ # even if it there are no messages available to return in the pull
756
+ # response. Otherwise, the system may wait (for a bounded amount of time)
757
+ # until at least one message is available, rather than returning no messages.
749
758
  #
750
759
  # See also {#listen} for the preferred way to process messages as they
751
760
  # become available.
@@ -755,31 +764,24 @@ module Google
755
764
  #
756
765
  # @return [Array<Google::Cloud::PubSub::ReceivedMessage>]
757
766
  #
758
- # @example
767
+ # @example The `immediate: false` option is now recommended to avoid adverse impacts on pull operations:
759
768
  # require "google/cloud/pubsub"
760
769
  #
761
770
  # pubsub = Google::Cloud::PubSub.new
762
771
  #
763
772
  # sub = pubsub.subscription "my-topic-sub"
764
- # sub.pull.each { |received_message| received_message.acknowledge! }
765
- #
766
- # @example A maximum number of messages returned can also be specified:
767
- # require "google/cloud/pubsub"
768
- #
769
- # pubsub = Google::Cloud::PubSub.new
770
- #
771
- # sub = pubsub.subscription "my-topic-sub"
772
- # sub.pull(max: 10).each do |received_message|
773
+ # received_messages = sub.pull immediate: false
774
+ # received_messages.each do |received_message|
773
775
  # received_message.acknowledge!
774
776
  # end
775
777
  #
776
- # @example The call can block until messages are available:
778
+ # @example A maximum number of messages returned can also be specified:
777
779
  # require "google/cloud/pubsub"
778
780
  #
779
781
  # pubsub = Google::Cloud::PubSub.new
780
782
  #
781
783
  # sub = pubsub.subscription "my-topic-sub"
782
- # received_messages = sub.pull immediate: false
784
+ # received_messages = sub.pull immediate: false, max: 10
783
785
  # received_messages.each do |received_message|
784
786
  # received_message.acknowledge!
785
787
  # end
@@ -1010,7 +1012,7 @@ module Google
1010
1012
  # pubsub = Google::Cloud::PubSub.new
1011
1013
  #
1012
1014
  # sub = pubsub.subscription "my-topic-sub"
1013
- # received_messages = sub.pull
1015
+ # received_messages = sub.pull immediate: false
1014
1016
  # sub.acknowledge received_messages
1015
1017
  #
1016
1018
  def acknowledge *messages
@@ -1045,7 +1047,7 @@ module Google
1045
1047
  # pubsub = Google::Cloud::PubSub.new
1046
1048
  #
1047
1049
  # sub = pubsub.subscription "my-topic-sub"
1048
- # received_messages = sub.pull
1050
+ # received_messages = sub.pull immediate: false
1049
1051
  # sub.modify_ack_deadline 120, received_messages
1050
1052
  #
1051
1053
  def modify_ack_deadline new_deadline, *messages
@@ -1143,7 +1145,7 @@ module Google
1143
1145
  #
1144
1146
  # snapshot = sub.create_snapshot
1145
1147
  #
1146
- # received_messages = sub.pull
1148
+ # received_messages = sub.pull immediate: false
1147
1149
  # sub.acknowledge received_messages
1148
1150
  #
1149
1151
  # sub.seek snapshot
@@ -1156,7 +1158,7 @@ module Google
1156
1158
  #
1157
1159
  # time = Time.now
1158
1160
  #
1159
- # received_messages = sub.pull
1161
+ # received_messages = sub.pull immediate: false
1160
1162
  # sub.acknowledge received_messages
1161
1163
  #
1162
1164
  # sub.seek time
@@ -588,6 +588,8 @@ module Google
588
588
  # @param [String, File] data The message payload. This will be converted
589
589
  # to bytes encoded as ASCII-8BIT.
590
590
  # @param [Hash] attributes Optional attributes for the message.
591
+ # @param [String] ordering_key Identifies related messages for which
592
+ # publish order should be respected.
591
593
  # @yield [batch] a block for publishing multiple messages in one
592
594
  # request
593
595
  # @yieldparam [BatchPublisher] batch the topic batch publisher
@@ -636,10 +638,24 @@ module Google
636
638
  # t.publish "task 3 completed", foo: :bif
637
639
  # end
638
640
  #
639
- def publish data = nil, attributes = {}
641
+ # @example Ordered messages are supported using ordering_key:
642
+ # require "google/cloud/pubsub"
643
+ #
644
+ # pubsub = Google::Cloud::PubSub.new
645
+ #
646
+ # topic = pubsub.topic "my-ordered-topic"
647
+ #
648
+ # # Ensure that message ordering is enabled.
649
+ # topic.enable_message_ordering!
650
+ #
651
+ # # Publish an ordered message with an ordering key.
652
+ # topic.publish "task completed",
653
+ # ordering_key: "task-key"
654
+ #
655
+ def publish data = nil, attributes = nil, ordering_key: nil, **extra_attrs, &block
640
656
  ensure_service!
641
- batch = BatchPublisher.new data, attributes
642
- yield batch if block_given?
657
+ batch = BatchPublisher.new data, attributes, ordering_key, extra_attrs
658
+ block&.call batch
643
659
  return nil if batch.messages.count.zero?
644
660
  publish_batch_messages batch
645
661
  end
@@ -16,7 +16,7 @@
16
16
  module Google
17
17
  module Cloud
18
18
  module PubSub
19
- VERSION = "2.5.0".freeze
19
+ VERSION = "2.6.0".freeze
20
20
  end
21
21
 
22
22
  Pubsub = PubSub unless const_defined? :Pubsub
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: google-cloud-pubsub
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.5.0
4
+ version: 2.6.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Mike Moore
@@ -9,7 +9,7 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2021-04-01 00:00:00.000000000 Z
12
+ date: 2021-04-19 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: concurrent-ruby