google-cloud-pubsub 2.1.1 → 2.7.0

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.
@@ -77,7 +77,9 @@ module Google
77
77
  ##
78
78
  # The name of the subscription.
79
79
  #
80
- # @return [String]
80
+ # @return [String] A fully-qualified subscription name in the form
81
+ # `projects/{project_id}/subscriptions/{subscription_id}`.
82
+ #
81
83
  def name
82
84
  return @resource_name if reference?
83
85
  @grpc.name
@@ -330,7 +332,7 @@ module Google
330
332
  # If {#expires_in=} is not set, a *default* value of of 31 days will be
331
333
  # used. The minimum allowed value is 1 day.
332
334
  #
333
- # Makes an API call to retrieve the value when called on a
335
+ # Makes an API call to retrieve the expires_in value when called on a
334
336
  # reference object. See {#reference?}.
335
337
  #
336
338
  # @return [Numeric, nil] The expiration duration, or `nil` if unset.
@@ -365,6 +367,9 @@ module Google
365
367
  # `attributes` field matches the filter are delivered on this subscription. If empty, then no messages are
366
368
  # filtered out.
367
369
  #
370
+ # Makes an API call to retrieve the filter value when called on a reference
371
+ # object. See {#reference?}.
372
+ #
368
373
  # @return [String] The frozen filter string.
369
374
  #
370
375
  def filter
@@ -377,8 +382,8 @@ module Google
377
382
  # otherwise `nil`. Dead lettering is done on a best effort basis. The same message might be dead lettered
378
383
  # multiple times.
379
384
  #
380
- # See also {#dead_letter_topic=}, {#dead_letter_max_delivery_attempts=} and
381
- # {#dead_letter_max_delivery_attempts}.
385
+ # See also {#dead_letter_topic=}, {#dead_letter_max_delivery_attempts=}, {#dead_letter_max_delivery_attempts}
386
+ # and {#remove_dead_letter_policy}.
382
387
  #
383
388
  # Makes an API call to retrieve the topic name when called on a reference object. See {#reference?}.
384
389
  #
@@ -409,7 +414,11 @@ module Google
409
414
  # The operation will fail if the topic does not exist. Users should ensure that there is a subscription attached
410
415
  # to this topic since messages published to a topic with no subscriptions are lost.
411
416
  #
412
- # See also {#dead_letter_topic}, {#dead_letter_max_delivery_attempts=} and {#dead_letter_max_delivery_attempts}.
417
+ # Makes an API call to retrieve the dead_letter_policy value when called on a
418
+ # reference object. See {#reference?}.
419
+ #
420
+ # See also {#dead_letter_topic}, {#dead_letter_max_delivery_attempts=}, {#dead_letter_max_delivery_attempts}
421
+ # and {#remove_dead_letter_policy}.
413
422
  #
414
423
  # @param [Topic] new_dead_letter_topic The topic to which dead letter messages for the subscription should be
415
424
  # published.
@@ -441,14 +450,15 @@ module Google
441
450
  # acknowledgement deadline has been exceeded for the message). A NACK is any call to ModifyAckDeadline with a 0
442
451
  # deadline. Note that client libraries may automatically extend ack_deadlines.
443
452
  #
444
- # This field will be honored on a best effort basis. If this parameter is 0, a default value of 5 is used.
453
+ # This field will be honored on a best effort basis. If this parameter is `nil` or `0`, a default value of `5`
454
+ # is used.
445
455
  #
446
- # See also {#dead_letter_max_delivery_attempts=}, {#dead_letter_topic=} and {#dead_letter_topic}.
456
+ # See also {#dead_letter_max_delivery_attempts=}, {#dead_letter_topic=}, {#dead_letter_topic}
457
+ # and {#remove_dead_letter_policy}.
447
458
  #
448
- # Makes an API call to retrieve the value when called on a reference object. See {#reference?}.
459
+ # Makes an API call to retrieve the dead_letter_policy when called on a reference object. See {#reference?}.
449
460
  #
450
- # @return [Integer, nil] A value between 5 and 100, or `nil` if no dead letter policy is configured. If this
451
- # value is 0, a default value of 5 is used.
461
+ # @return [Integer, nil] A value between `5` and `100`, or `nil` if no dead letter policy is configured.
452
462
  #
453
463
  # @example
454
464
  # require "google/cloud/pubsub"
@@ -475,10 +485,15 @@ module Google
475
485
  #
476
486
  # This field will be honored on a best effort basis. If this parameter is 0, a default value of 5 is used.
477
487
  #
478
- # The dead letter topic must also be set. See {#dead_letter_topic=} and {#dead_letter_topic}.
488
+ # Makes an API call to retrieve the dead_letter_policy when called on a reference object. See {#reference?}.
489
+ #
490
+ # The dead letter topic must be set first. See {#dead_letter_topic=}, {#dead_letter_topic} and
491
+ # {#remove_dead_letter_policy}.
479
492
  #
480
- # @param [Integer] new_dead_letter_max_delivery_attempts A value between 5 and 100. If this parameter is 0, a
481
- # default value of 5 is used.
493
+ # @param [Integer, nil] new_dead_letter_max_delivery_attempts A value between 5 and 100. If this parameter is
494
+ # `nil` or `0`, a default value of 5 is used.
495
+ #
496
+ # @raise [ArgumentError] if the dead letter topic has not been set. See {#dead_letter_topic=}.
482
497
  #
483
498
  # @example
484
499
  # require "google/cloud/pubsub"
@@ -503,14 +518,48 @@ module Google
503
518
  @resource_name = nil
504
519
  end
505
520
 
521
+ ##
522
+ # Removes an existing dead letter policy. A dead letter policy specifies the conditions for dead lettering
523
+ # messages in the subscription. If a dead letter policy is not set, dead lettering is disabled.
524
+ #
525
+ # Makes an API call to retrieve the dead_letter_policy when called on a reference object. See {#reference?}.
526
+ #
527
+ # See {#dead_letter_topic}, {#dead_letter_topic=}, {#dead_letter_max_delivery_attempts} and
528
+ # {#dead_letter_max_delivery_attempts=}.
529
+ #
530
+ # @return [Boolean] `true` if an existing dead letter policy was removed, `false` if no existing dead letter
531
+ # policy was present.
532
+ #
533
+ # @example
534
+ # require "google/cloud/pubsub"
535
+ #
536
+ # pubsub = Google::Cloud::PubSub.new
537
+ #
538
+ # sub = pubsub.subscription "my-topic-sub"
539
+ #
540
+ # sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
541
+ # sub.dead_letter_max_delivery_attempts #=> 10
542
+ #
543
+ # sub.remove_dead_letter_policy
544
+ #
545
+ # sub.dead_letter_topic #=> nil
546
+ # sub.dead_letter_max_delivery_attempts #=> nil
547
+ #
548
+ def remove_dead_letter_policy
549
+ ensure_grpc!
550
+ return false if @grpc.dead_letter_policy.nil?
551
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, dead_letter_policy: nil
552
+ @grpc = service.update_subscription update_grpc, :dead_letter_policy
553
+ true
554
+ end
555
+
506
556
  ##
507
557
  # A policy that specifies how Cloud Pub/Sub retries message delivery for this subscription. If `nil`, the
508
558
  # default retry policy is applied. This generally implies that messages will be retried as soon as possible
509
559
  # for healthy subscribers. Retry Policy will be triggered on NACKs or acknowledgement deadline exceeded events
510
560
  # for a given message.
511
561
  #
512
- # **EXPERIMENTAL:** This API might be changed in backward-incompatible ways and is not recommended for
513
- # production use. It is not subject to any SLA or deprecation policy.
562
+ # Makes an API call to retrieve the retry_policy when called on a reference object. See {#reference?}.
514
563
  #
515
564
  # @return [RetryPolicy, nil] The retry policy for the subscription, or `nil`.
516
565
  #
@@ -538,9 +587,6 @@ module Google
538
587
  # for healthy subscribers. Retry Policy will be triggered on NACKs or acknowledgement deadline exceeded events
539
588
  # for a given message.
540
589
  #
541
- # **EXPERIMENTAL:** This API might be changed in backward-incompatible ways and is not recommended for
542
- # production use. It is not subject to any SLA or deprecation policy.
543
- #
544
590
  # @param [RetryPolicy, nil] new_retry_policy A new retry policy for the subscription, or `nil`.
545
591
  #
546
592
  # @example
@@ -556,10 +602,11 @@ module Google
556
602
  # sub.retry_policy.maximum_backoff #=> 300
557
603
  #
558
604
  def retry_policy= new_retry_policy
559
- ensure_grpc!
605
+ ensure_service!
560
606
  new_retry_policy = new_retry_policy.to_grpc if new_retry_policy
561
607
  update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, retry_policy: new_retry_policy
562
608
  @grpc = service.update_subscription update_grpc, :retry_policy
609
+ @resource_name = nil
563
610
  end
564
611
 
565
612
  ##
@@ -591,7 +638,7 @@ module Google
591
638
  #
592
639
  # See {Topic#subscribe} and {#detach}.
593
640
  #
594
- # Makes an API call to retrieve the value when called on a
641
+ # Makes an API call to retrieve the detached value when called on a
595
642
  # reference object. See {#reference?}.
596
643
  #
597
644
  # @return [Boolean]
@@ -686,19 +733,28 @@ module Google
686
733
  end
687
734
 
688
735
  ##
689
- # Pulls messages from the server. Returns an empty list if there are no
690
- # messages available in the backlog. Raises an ApiError with status
691
- # `UNAVAILABLE` if there are too many concurrent pull requests pending
692
- # 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.
693
742
  #
694
743
  # See also {#listen} for the preferred way to process messages as they
695
744
  # become available.
696
745
  #
697
- # @param [Boolean] immediate When `true` the system will respond
698
- # immediately even if it is not able to return messages. When `false`
699
- # the system is allowed to wait until it can return least one message.
700
- # No messages are returned when a request times out. The default value
701
- # 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.
702
758
  #
703
759
  # See also {#listen} for the preferred way to process messages as they
704
760
  # become available.
@@ -708,31 +764,24 @@ module Google
708
764
  #
709
765
  # @return [Array<Google::Cloud::PubSub::ReceivedMessage>]
710
766
  #
711
- # @example
712
- # require "google/cloud/pubsub"
713
- #
714
- # pubsub = Google::Cloud::PubSub.new
715
- #
716
- # sub = pubsub.subscription "my-topic-sub"
717
- # sub.pull.each { |received_message| received_message.acknowledge! }
718
- #
719
- # @example A maximum number of messages returned can also be specified:
767
+ # @example The `immediate: false` option is now recommended to avoid adverse impacts on pull operations:
720
768
  # require "google/cloud/pubsub"
721
769
  #
722
770
  # pubsub = Google::Cloud::PubSub.new
723
771
  #
724
772
  # sub = pubsub.subscription "my-topic-sub"
725
- # sub.pull(max: 10).each do |received_message|
773
+ # received_messages = sub.pull immediate: false
774
+ # received_messages.each do |received_message|
726
775
  # received_message.acknowledge!
727
776
  # end
728
777
  #
729
- # @example The call can block until messages are available:
778
+ # @example A maximum number of messages returned can also be specified:
730
779
  # require "google/cloud/pubsub"
731
780
  #
732
781
  # pubsub = Google::Cloud::PubSub.new
733
782
  #
734
783
  # sub = pubsub.subscription "my-topic-sub"
735
- # received_messages = sub.pull immediate: false
784
+ # received_messages = sub.pull immediate: false, max: 10
736
785
  # received_messages.each do |received_message|
737
786
  # received_message.acknowledge!
738
787
  # end
@@ -832,6 +881,9 @@ module Google
832
881
  # Default is 1,000. (Note: replaces `:limit`, which is deprecated.)
833
882
  # * `:max_outstanding_bytes` [Integer] The total byte size of received messages to be collected by
834
883
  # subscriber. Default is 100,000,000 (100MB). (Note: replaces `:bytesize`, which is deprecated.)
884
+ # * `:use_legacy_flow_control` [Boolean] Disables enforcing flow control settings at the Cloud PubSub
885
+ # server and the less accurate method of only enforcing flow control at the client side is used instead.
886
+ # Default is false.
835
887
  # * `:max_total_lease_duration` [Integer] The number of seconds that received messages can be held awaiting
836
888
  # processing. Default is 3,600 (1 hour). (Note: replaces `:extension`, which is deprecated.)
837
889
  # * `:max_duration_per_lease_extension` [Integer] The maximum amount of time in seconds for a single lease
@@ -960,7 +1012,7 @@ module Google
960
1012
  # pubsub = Google::Cloud::PubSub.new
961
1013
  #
962
1014
  # sub = pubsub.subscription "my-topic-sub"
963
- # received_messages = sub.pull
1015
+ # received_messages = sub.pull immediate: false
964
1016
  # sub.acknowledge received_messages
965
1017
  #
966
1018
  def acknowledge *messages
@@ -995,7 +1047,7 @@ module Google
995
1047
  # pubsub = Google::Cloud::PubSub.new
996
1048
  #
997
1049
  # sub = pubsub.subscription "my-topic-sub"
998
- # received_messages = sub.pull
1050
+ # received_messages = sub.pull immediate: false
999
1051
  # sub.modify_ack_deadline 120, received_messages
1000
1052
  #
1001
1053
  def modify_ack_deadline new_deadline, *messages
@@ -1016,14 +1068,19 @@ module Google
1016
1068
  # * Any messages published to the subscription's topic following the
1017
1069
  # successful completion of the `create_snapshot` operation.
1018
1070
  #
1019
- # @param [String, nil] snapshot_name Name of the new snapshot. If the
1020
- # name is not provided, the server will assign a random name
1021
- # for this snapshot on the same project as the subscription. The
1022
- # format is `projects/{project}/snapshots/{snap}`. The name must start
1023
- # with a letter, and contain only letters ([A-Za-z]), numbers
1024
- # ([0-9], dashes (-), underscores (_), periods (.), tildes (~), plus
1025
- # (+) or percent signs (%). It must be between 3 and 255 characters in
1026
- # length, and it must not start with "goog". Optional.
1071
+ # @param [String, nil] snapshot_name Name of the new snapshot. Optional.
1072
+ # If the name is not provided, the server will assign a random name
1073
+ # for this snapshot on the same project as the subscription.
1074
+ # The value can be a simple snapshot ID (relative name), in which
1075
+ # case the current project ID will be supplied, or a fully-qualified
1076
+ # snapshot name in the form
1077
+ # `projects/{project_id}/snapshots/{snapshot_id}`.
1078
+ #
1079
+ # The snapshot ID (relative name) must start with a letter, and
1080
+ # contain only letters (`[A-Za-z]`), numbers (`[0-9]`), dashes (`-`),
1081
+ # underscores (`_`), periods (`.`), tildes (`~`), plus (`+`) or percent
1082
+ # signs (`%`). It must be between 3 and 255 characters in length, and
1083
+ # it must not start with `goog`.
1027
1084
  # @param [Hash] labels A hash of user-provided labels associated with
1028
1085
  # the snapshot. You can use these to organize and group your
1029
1086
  # snapshots. Label keys and values can be no longer than 63
@@ -1088,7 +1145,7 @@ module Google
1088
1145
  #
1089
1146
  # snapshot = sub.create_snapshot
1090
1147
  #
1091
- # received_messages = sub.pull
1148
+ # received_messages = sub.pull immediate: false
1092
1149
  # sub.acknowledge received_messages
1093
1150
  #
1094
1151
  # sub.seek snapshot
@@ -1101,7 +1158,7 @@ module Google
1101
1158
  #
1102
1159
  # time = Time.now
1103
1160
  #
1104
- # received_messages = sub.pull
1161
+ # received_messages = sub.pull immediate: false
1105
1162
  # sub.acknowledge received_messages
1106
1163
  #
1107
1164
  # sub.seek time
@@ -130,12 +130,12 @@ module Google
130
130
  # puts subscription.name
131
131
  # end
132
132
  #
133
- def all request_limit: nil
133
+ def all request_limit: nil, &block
134
134
  request_limit = request_limit.to_i if request_limit
135
135
  return enum_for :all, request_limit: request_limit unless block_given?
136
136
  results = self
137
137
  loop do
138
- results.each { |r| yield r }
138
+ results.each(&block)
139
139
  if request_limit
140
140
  request_limit -= 1
141
141
  break if request_limit.negative?
@@ -85,10 +85,10 @@ module Google
85
85
  end
86
86
 
87
87
  ##
88
- # The name of the topic in the form of
89
- # "/projects/project-identifier/topics/topic-name".
88
+ # The name of the topic.
90
89
  #
91
- # @return [String]
90
+ # @return [String] A fully-qualified topic name in the form
91
+ # `projects/{project_id}/topics/{topic_id}`.
92
92
  #
93
93
  def name
94
94
  return @resource_name if reference?
@@ -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
  #
@@ -255,11 +327,17 @@ module Google
255
327
  ##
256
328
  # Creates a new {Subscription} object on the current Topic.
257
329
  #
258
- # @param [String] subscription_name Name of the new subscription. Must
259
- # start with a letter, and contain only letters ([A-Za-z]), numbers
260
- # ([0-9], dashes (-), underscores (_), periods (.), tildes (~), plus
261
- # (+) or percent signs (%). It must be between 3 and 255 characters in
262
- # length, and it must not start with "goog". Required.
330
+ # @param [String] subscription_name Name of the new subscription. Required.
331
+ # The value can be a simple subscription ID (relative name), in which
332
+ # case the current project ID will be supplied, or a fully-qualified
333
+ # subscription name in the form
334
+ # `projects/{project_id}/subscriptions/{subscription_id}`.
335
+ #
336
+ # The subscription ID (relative name) must start with a letter, and
337
+ # contain only letters (`[A-Za-z]`), numbers (`[0-9]`), dashes (`-`),
338
+ # underscores (`_`), periods (`.`), tildes (`~`), plus (`+`) or percent
339
+ # signs (`%`). It must be between 3 and 255 characters in length, and
340
+ # it must not start with `goog`.
263
341
  # @param [Integer] deadline The maximum number of seconds after a
264
342
  # subscriber receives a message before the subscriber should
265
343
  # acknowledge the message.
@@ -309,9 +387,6 @@ module Google
309
387
  # will be retried as soon as possible for healthy subscribers. Retry Policy will be triggered on NACKs or
310
388
  # acknowledgement deadline exceeded events for a given message.
311
389
  #
312
- # **EXPERIMENTAL:** This API might be changed in backward-incompatible ways and is not recommended for
313
- # production use. It is not subject to any SLA or deprecation policy.
314
- #
315
390
  # @return [Google::Cloud::PubSub::Subscription]
316
391
  #
317
392
  # @example
@@ -418,7 +493,11 @@ module Google
418
493
  ##
419
494
  # Retrieves subscription by name.
420
495
  #
421
- # @param [String] subscription_name Name of a subscription.
496
+ # @param [String] subscription_name Name of a subscription. The value
497
+ # can be a simple subscription ID (relative name), in which case the
498
+ # current project ID will be supplied, or a fully-qualified
499
+ # subscription name in the form
500
+ # `projects/{project_id}/subscriptions/{subscription_id}`.
422
501
  # @param [Boolean] skip_lookup Optionally create a {Subscription} object
423
502
  # without verifying the subscription resource exists on the Pub/Sub
424
503
  # service. Calls made on this object will raise errors if the service
@@ -509,6 +588,8 @@ module Google
509
588
  # @param [String, File] data The message payload. This will be converted
510
589
  # to bytes encoded as ASCII-8BIT.
511
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.
512
593
  # @yield [batch] a block for publishing multiple messages in one
513
594
  # request
514
595
  # @yieldparam [BatchPublisher] batch the topic batch publisher
@@ -557,10 +638,24 @@ module Google
557
638
  # t.publish "task 3 completed", foo: :bif
558
639
  # end
559
640
  #
560
- 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
561
656
  ensure_service!
562
- batch = BatchPublisher.new data, attributes
563
- yield batch if block_given?
657
+ batch = BatchPublisher.new data, attributes, ordering_key, extra_attrs
658
+ block&.call batch
564
659
  return nil if batch.messages.count.zero?
565
660
  publish_batch_messages batch
566
661
  end
@@ -589,6 +684,11 @@ module Google
589
684
  # @note At the time of this release, ordering keys are not yet publicly
590
685
  # enabled and requires special project enablements.
591
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
+ #
592
692
  # @param [String, File] data The message payload. This will be converted
593
693
  # to bytes encoded as ASCII-8BIT.
594
694
  # @param [Hash] attributes Optional attributes for the message.
@@ -608,6 +708,13 @@ module Google
608
708
  # message with an `ordering_key` that has already failed when
609
709
  # publishing. Use {#resume_publish} to allow this `ordering_key` to be
610
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.
611
718
  #
612
719
  # @example
613
720
  # require "google/cloud/pubsub"
@@ -670,7 +777,7 @@ module Google
670
777
  def publish_async data = nil, attributes = nil, ordering_key: nil, **extra_attrs, &callback
671
778
  ensure_service!
672
779
 
673
- @async_publisher ||= AsyncPublisher.new name, service, @async_opts
780
+ @async_publisher ||= AsyncPublisher.new name, service, **@async_opts
674
781
  @async_publisher.publish data, attributes, ordering_key: ordering_key, **extra_attrs, &callback
675
782
  end
676
783
 
@@ -686,7 +793,7 @@ module Google
686
793
  # {Subscription#listen}, and {Message#ordering_key}.
687
794
  #
688
795
  def enable_message_ordering!
689
- @async_publisher ||= AsyncPublisher.new name, service, @async_opts
796
+ @async_publisher ||= AsyncPublisher.new name, service, **@async_opts
690
797
  @async_publisher.enable_message_ordering!
691
798
  end
692
799
 
@@ -702,7 +809,7 @@ module Google
702
809
  # @return [Boolean]
703
810
  #
704
811
  def message_ordering?
705
- @async_publisher ||= AsyncPublisher.new name, service, @async_opts
812
+ @async_publisher ||= AsyncPublisher.new name, service, **@async_opts
706
813
  @async_publisher.message_ordering?
707
814
  end
708
815
 
@@ -715,7 +822,7 @@ module Google
715
822
  # @return [boolean] `true` when resumed, `false` otherwise.
716
823
  #
717
824
  def resume_publish ordering_key
718
- @async_publisher ||= AsyncPublisher.new name, service, @async_opts
825
+ @async_publisher ||= AsyncPublisher.new name, service, **@async_opts
719
826
  @async_publisher.resume_publish ordering_key
720
827
  end
721
828