google-cloud-pubsub 2.4.0 → 2.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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
@@ -233,6 +233,78 @@ module Google
233
233
  @resource_name = nil
234
234
  end
235
235
 
236
+ ##
237
+ # The name of the schema that messages published should be validated against, if schema settings are configured
238
+ # for the topic. The value is a fully-qualified schema name in the form
239
+ # `projects/{project_id}/schemas/{schema_id}`. If present, {#message_encoding} should also be present. The value
240
+ # of this field will be `_deleted-schema_` if the schema has been deleted.
241
+ #
242
+ # Makes an API call to retrieve the schema settings when called on a reference object. See {#reference?}.
243
+ #
244
+ # @return [String, nil] The schema name, or `nil` if schema settings are not configured for the topic.
245
+ #
246
+ # @example
247
+ # require "google/cloud/pubsub"
248
+ #
249
+ # pubsub = Google::Cloud::PubSub.new
250
+ #
251
+ # topic = pubsub.topic "my-topic"
252
+ #
253
+ # topic.schema_name #=> "projects/my-project/schemas/my-schema"
254
+ #
255
+ def schema_name
256
+ ensure_grpc!
257
+ @grpc.schema_settings&.schema
258
+ end
259
+
260
+ ##
261
+ # The encoding of messages validated against the schema identified by {#schema_name}. If present, {#schema_name}
262
+ # should also be present. Values include:
263
+ #
264
+ # * `JSON` - JSON encoding.
265
+ # * `BINARY` - Binary encoding, as defined by the schema type. For some schema types, binary encoding may not be
266
+ # available.
267
+ #
268
+ # Makes an API call to retrieve the schema settings when called on a reference object. See {#reference?}.
269
+ #
270
+ # @return [Symbol, nil] The schema encoding, or `nil` if schema settings are not configured for the topic.
271
+ #
272
+ # @example
273
+ # require "google/cloud/pubsub"
274
+ #
275
+ # pubsub = Google::Cloud::PubSub.new
276
+ #
277
+ # topic = pubsub.topic "my-topic"
278
+ #
279
+ # topic.message_encoding #=> :JSON
280
+ #
281
+ def message_encoding
282
+ ensure_grpc!
283
+ @grpc.schema_settings&.encoding
284
+ end
285
+
286
+ ##
287
+ # Checks if the encoding of messages in the schema settings is `BINARY`. See {#message_encoding}.
288
+ #
289
+ # Makes an API call to retrieve the schema settings when called on a reference object. See {#reference?}.
290
+ #
291
+ # @return [Boolean] `true` when `BINARY`, `false` if not `BINARY` or schema settings is not set.
292
+ #
293
+ def message_encoding_binary?
294
+ message_encoding.to_s.upcase == "BINARY"
295
+ end
296
+
297
+ ##
298
+ # Checks if the encoding of messages in the schema settings is `JSON`. See {#message_encoding}.
299
+ #
300
+ # Makes an API call to retrieve the schema settings when called on a reference object. See {#reference?}.
301
+ #
302
+ # @return [Boolean] `true` when `JSON`, `false` if not `JSON` or schema settings is not set.
303
+ #
304
+ def message_encoding_json?
305
+ message_encoding.to_s.upcase == "JSON"
306
+ end
307
+
236
308
  ##
237
309
  # Permanently deletes the topic.
238
310
  #
@@ -516,6 +588,8 @@ module Google
516
588
  # @param [String, File] data The message payload. This will be converted
517
589
  # to bytes encoded as ASCII-8BIT.
518
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.
519
593
  # @yield [batch] a block for publishing multiple messages in one
520
594
  # request
521
595
  # @yieldparam [BatchPublisher] batch the topic batch publisher
@@ -564,10 +638,24 @@ module Google
564
638
  # t.publish "task 3 completed", foo: :bif
565
639
  # end
566
640
  #
567
- 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
568
656
  ensure_service!
569
- batch = BatchPublisher.new data, attributes
570
- yield batch if block_given?
657
+ batch = BatchPublisher.new data, attributes, ordering_key, extra_attrs
658
+ block&.call batch
571
659
  return nil if batch.messages.count.zero?
572
660
  publish_batch_messages batch
573
661
  end
@@ -596,6 +684,11 @@ module Google
596
684
  # @note At the time of this release, ordering keys are not yet publicly
597
685
  # enabled and requires special project enablements.
598
686
  #
687
+ # Publisher flow control limits the number of outstanding messages that
688
+ # are allowed to wait to be published. See the `flow_control` key in the
689
+ # `async` parameter in {Project#topic} for more information about publisher
690
+ # flow control settings.
691
+ #
599
692
  # @param [String, File] data The message payload. This will be converted
600
693
  # to bytes encoded as ASCII-8BIT.
601
694
  # @param [Hash] attributes Optional attributes for the message.
@@ -615,6 +708,13 @@ module Google
615
708
  # message with an `ordering_key` that has already failed when
616
709
  # publishing. Use {#resume_publish} to allow this `ordering_key` to be
617
710
  # published again.
711
+ # @raise [Google::Cloud::PubSub::FlowControlLimitError] when publish flow
712
+ # control limits are exceeded, and the `async` parameter key
713
+ # `flow_control.limit_exceeded_behavior` is set to `:error` or `:block`.
714
+ # If `flow_control.limit_exceeded_behavior` is set to `:block`, this error
715
+ # will be raised only when a limit would be exceeded by a single message.
716
+ # See the `async` parameter in {Project#topic} for more information about
717
+ # `flow_control` settings.
618
718
  #
619
719
  # @example
620
720
  # require "google/cloud/pubsub"
@@ -16,7 +16,7 @@
16
16
  module Google
17
17
  module Cloud
18
18
  module PubSub
19
- VERSION = "2.4.0".freeze
19
+ VERSION = "2.7.1".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.4.0
4
+ version: 2.7.1
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-03-11 00:00:00.000000000 Z
12
+ date: 2021-07-08 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: concurrent-ruby
@@ -67,6 +67,20 @@ dependencies:
67
67
  - - "~>"
68
68
  - !ruby/object:Gem::Version
69
69
  version: '1.1'
70
+ - !ruby/object:Gem::Dependency
71
+ name: avro
72
+ requirement: !ruby/object:Gem::Requirement
73
+ requirements:
74
+ - - "~>"
75
+ - !ruby/object:Gem::Version
76
+ version: '1.10'
77
+ type: :development
78
+ prerelease: false
79
+ version_requirements: !ruby/object:Gem::Requirement
80
+ requirements:
81
+ - - "~>"
82
+ - !ruby/object:Gem::Version
83
+ version: '1.10'
70
84
  - !ruby/object:Gem::Dependency
71
85
  name: google-style
72
86
  requirement: !ruby/object:Gem::Requirement
@@ -219,12 +233,15 @@ files:
219
233
  - lib/google/cloud/pubsub/convert.rb
220
234
  - lib/google/cloud/pubsub/credentials.rb
221
235
  - lib/google/cloud/pubsub/errors.rb
236
+ - lib/google/cloud/pubsub/flow_controller.rb
222
237
  - lib/google/cloud/pubsub/message.rb
223
238
  - lib/google/cloud/pubsub/policy.rb
224
239
  - lib/google/cloud/pubsub/project.rb
225
240
  - lib/google/cloud/pubsub/publish_result.rb
226
241
  - lib/google/cloud/pubsub/received_message.rb
227
242
  - lib/google/cloud/pubsub/retry_policy.rb
243
+ - lib/google/cloud/pubsub/schema.rb
244
+ - lib/google/cloud/pubsub/schema/list.rb
228
245
  - lib/google/cloud/pubsub/service.rb
229
246
  - lib/google/cloud/pubsub/snapshot.rb
230
247
  - lib/google/cloud/pubsub/snapshot/list.rb
@@ -259,7 +276,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
259
276
  - !ruby/object:Gem::Version
260
277
  version: '0'
261
278
  requirements: []
262
- rubygems_version: 3.2.13
279
+ rubygems_version: 3.2.17
263
280
  signing_key:
264
281
  specification_version: 4
265
282
  summary: API Client library for Google Cloud Pub/Sub