google-cloud-pubsub 1.0.2 → 2.19.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.
Files changed (58) hide show
  1. checksums.yaml +4 -4
  2. data/AUTHENTICATION.md +16 -54
  3. data/CHANGELOG.md +464 -0
  4. data/CONTRIBUTING.md +328 -116
  5. data/EMULATOR.md +1 -1
  6. data/LOGGING.md +94 -2
  7. data/OVERVIEW.md +121 -68
  8. data/TROUBLESHOOTING.md +2 -8
  9. data/lib/google/cloud/pubsub/acknowledge_result.rb +79 -0
  10. data/lib/google/cloud/pubsub/async_publisher/batch.rb +319 -0
  11. data/lib/google/cloud/pubsub/async_publisher.rb +231 -156
  12. data/lib/google/cloud/pubsub/batch_publisher.rb +60 -30
  13. data/lib/google/cloud/pubsub/convert.rb +33 -7
  14. data/lib/google/cloud/pubsub/credentials.rb +2 -2
  15. data/lib/google/cloud/pubsub/errors.rb +93 -0
  16. data/lib/google/cloud/pubsub/flow_controller.rb +137 -0
  17. data/lib/google/cloud/pubsub/message.rb +45 -4
  18. data/lib/google/cloud/pubsub/policy.rb +3 -2
  19. data/lib/google/cloud/pubsub/project.rb +316 -49
  20. data/lib/google/cloud/pubsub/publish_result.rb +6 -1
  21. data/lib/google/cloud/pubsub/received_message.rb +171 -10
  22. data/lib/google/cloud/pubsub/retry_policy.rb +88 -0
  23. data/lib/google/cloud/pubsub/schema/list.rb +180 -0
  24. data/lib/google/cloud/pubsub/schema.rb +310 -0
  25. data/lib/google/cloud/pubsub/service.rb +285 -269
  26. data/lib/google/cloud/pubsub/snapshot/list.rb +4 -6
  27. data/lib/google/cloud/pubsub/snapshot.rb +5 -2
  28. data/lib/google/cloud/pubsub/subscriber/inventory.rb +69 -32
  29. data/lib/google/cloud/pubsub/subscriber/sequencer.rb +115 -0
  30. data/lib/google/cloud/pubsub/subscriber/stream.rb +108 -49
  31. data/lib/google/cloud/pubsub/subscriber/timed_unary_buffer.rb +191 -30
  32. data/lib/google/cloud/pubsub/subscriber.rb +155 -45
  33. data/lib/google/cloud/pubsub/subscription/list.rb +4 -6
  34. data/lib/google/cloud/pubsub/subscription/push_config.rb +55 -31
  35. data/lib/google/cloud/pubsub/subscription.rb +561 -77
  36. data/lib/google/cloud/pubsub/topic/list.rb +4 -6
  37. data/lib/google/cloud/pubsub/topic.rb +372 -52
  38. data/lib/google/cloud/pubsub/version.rb +1 -1
  39. data/lib/google/cloud/pubsub.rb +35 -46
  40. data/lib/google-cloud-pubsub.rb +21 -27
  41. metadata +26 -189
  42. data/lib/google/cloud/pubsub/v1/credentials.rb +0 -41
  43. data/lib/google/cloud/pubsub/v1/doc/google/iam/v1/iam_policy.rb +0 -21
  44. data/lib/google/cloud/pubsub/v1/doc/google/iam/v1/options.rb +0 -21
  45. data/lib/google/cloud/pubsub/v1/doc/google/iam/v1/policy.rb +0 -21
  46. data/lib/google/cloud/pubsub/v1/doc/google/protobuf/duration.rb +0 -91
  47. data/lib/google/cloud/pubsub/v1/doc/google/protobuf/empty.rb +0 -29
  48. data/lib/google/cloud/pubsub/v1/doc/google/protobuf/field_mask.rb +0 -222
  49. data/lib/google/cloud/pubsub/v1/doc/google/protobuf/timestamp.rb +0 -113
  50. data/lib/google/cloud/pubsub/v1/doc/google/pubsub/v1/pubsub.rb +0 -744
  51. data/lib/google/cloud/pubsub/v1/doc/google/type/expr.rb +0 -19
  52. data/lib/google/cloud/pubsub/v1/publisher_client.rb +0 -786
  53. data/lib/google/cloud/pubsub/v1/publisher_client_config.json +0 -105
  54. data/lib/google/cloud/pubsub/v1/subscriber_client.rb +0 -1385
  55. data/lib/google/cloud/pubsub/v1/subscriber_client_config.json +0 -138
  56. data/lib/google/cloud/pubsub/v1.rb +0 -17
  57. data/lib/google/pubsub/v1/pubsub_pb.rb +0 -249
  58. data/lib/google/pubsub/v1/pubsub_services_pb.rb +0 -211
@@ -18,8 +18,10 @@ require "google/cloud/errors"
18
18
  require "google/cloud/pubsub/subscription/list"
19
19
  require "google/cloud/pubsub/subscription/push_config"
20
20
  require "google/cloud/pubsub/received_message"
21
+ require "google/cloud/pubsub/retry_policy"
21
22
  require "google/cloud/pubsub/snapshot"
22
23
  require "google/cloud/pubsub/subscriber"
24
+ require "google/cloud/pubsub/v1"
23
25
 
24
26
  module Google
25
27
  module Cloud
@@ -41,12 +43,19 @@ module Google
41
43
  # received_message.acknowledge!
42
44
  # end
43
45
  #
44
- # # Start background threads that will call the block passed to listen.
45
- # subscriber.start
46
+ # # Handle exceptions from listener
47
+ # subscriber.on_error do |exception|
48
+ # puts "Exception: #{exception.class} #{exception.message}"
49
+ # end
46
50
  #
47
- # # Shut down the subscriber when ready to stop receiving messages.
48
- # subscriber.stop.wait!
51
+ # # Gracefully shut down the subscriber
52
+ # at_exit do
53
+ # subscriber.stop!
54
+ # end
49
55
  #
56
+ # # Start background threads that will call the block passed to listen.
57
+ # subscriber.start
58
+ # sleep
50
59
  class Subscription
51
60
  ##
52
61
  # @private The Service object.
@@ -68,7 +77,9 @@ module Google
68
77
  ##
69
78
  # The name of the subscription.
70
79
  #
71
- # @return [String]
80
+ # @return [String] A fully-qualified subscription name in the form
81
+ # `projects/{project_id}/subscriptions/{subscription_id}`.
82
+ #
72
83
  def name
73
84
  return @resource_name if reference?
74
85
  @grpc.name
@@ -117,10 +128,8 @@ module Google
117
128
  # @param [Integer] new_deadline The new deadline value.
118
129
  #
119
130
  def deadline= new_deadline
120
- update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
121
- name: name, ack_deadline_seconds: new_deadline
122
- @grpc = service.update_subscription update_grpc,
123
- :ack_deadline_seconds
131
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, ack_deadline_seconds: new_deadline
132
+ @grpc = service.update_subscription update_grpc, :ack_deadline_seconds
124
133
  @resource_name = nil
125
134
  end
126
135
 
@@ -148,10 +157,9 @@ module Google
148
157
  # value.
149
158
  #
150
159
  def retain_acked= new_retain_acked
151
- update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
152
- name: name, retain_acked_messages: !(!new_retain_acked)
153
- @grpc = service.update_subscription update_grpc,
154
- :retain_acked_messages
160
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name,
161
+ retain_acked_messages: !(!new_retain_acked)
162
+ @grpc = service.update_subscription update_grpc, :retain_acked_messages
155
163
  @resource_name = nil
156
164
  end
157
165
 
@@ -160,9 +168,8 @@ module Google
160
168
  # backlog, from the moment a message is published. If
161
169
  # {#retain_acked} is `true`, then this also configures the retention of
162
170
  # acknowledged messages, and thus configures how far back in time a
163
- # {#seek} can be done. Cannot be more than 604,800 seconds (7 days) or
164
- # less than 600 seconds (10 minutes). Default is 604,800 seconds (7
165
- # days).
171
+ # {#seek} can be done. Cannot be less than 600 (10 minutes) or more
172
+ # than 604,800 (7 days). Default is 604,800 seconds (7 days).
166
173
  #
167
174
  # Makes an API call to retrieve the retention value when called on a
168
175
  # reference object. See {#reference?}.
@@ -181,17 +188,34 @@ module Google
181
188
  #
182
189
  def retention= new_retention
183
190
  new_retention_duration = Convert.number_to_duration new_retention
184
- update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
185
- name: name, message_retention_duration: new_retention_duration
186
- @grpc = service.update_subscription update_grpc,
187
- :message_retention_duration
191
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name,
192
+ message_retention_duration: new_retention_duration
193
+ @grpc = service.update_subscription update_grpc, :message_retention_duration
188
194
  @resource_name = nil
189
195
  end
190
196
 
197
+ ##
198
+ # Indicates the minimum duration for which a message is retained after
199
+ # it is published to the subscription's topic. If this field is set,
200
+ # messages published to the subscription's topic in the last
201
+ # `topic_message_retention_duration` are always available to subscribers.
202
+ # Output only. See {Topic#retention}.
203
+ #
204
+ # Makes an API call to retrieve the retention value when called on a
205
+ # reference object. See {#reference?}.
206
+ #
207
+ # @return [Numeric, nil] The topic message retention duration in seconds,
208
+ # or `nil` if not set.
209
+ #
210
+ def topic_retention
211
+ ensure_grpc!
212
+ Convert.duration_to_number @grpc.topic_message_retention_duration
213
+ end
214
+
191
215
  ##
192
216
  # Returns the URL locating the endpoint to which messages should be
193
217
  # pushed. For example, a Webhook endpoint might use
194
- # "https://example.com/push".
218
+ # `https://example.com/push`.
195
219
  #
196
220
  # Makes an API call to retrieve the endpoint value when called on a
197
221
  # reference object. See {#reference?}.
@@ -200,12 +224,12 @@ module Google
200
224
  #
201
225
  def endpoint
202
226
  ensure_grpc!
203
- @grpc.push_config.push_endpoint if @grpc.push_config
227
+ @grpc.push_config&.push_endpoint
204
228
  end
205
229
 
206
230
  ##
207
231
  # Sets the URL locating the endpoint to which messages should be pushed.
208
- # For example, a Webhook endpoint might use "https://example.com/push".
232
+ # For example, a Webhook endpoint might use `https://example.com/push`.
209
233
  #
210
234
  # @param [String] new_endpoint The new endpoint value.
211
235
  #
@@ -271,8 +295,7 @@ module Google
271
295
  new_config = config.to_grpc
272
296
 
273
297
  if old_config != new_config # has the object been changed?
274
- update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
275
- name: name, push_config: new_config
298
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, push_config: new_config
276
299
  @grpc = service.update_subscription update_grpc, :push_config
277
300
  end
278
301
  end
@@ -280,6 +303,56 @@ module Google
280
303
  config.freeze
281
304
  end
282
305
 
306
+ ##
307
+ # Inspect the Subscription's bigquery configuration settings. The
308
+ # configuration can be changed by modifying the values in the method's
309
+ # block.
310
+ #
311
+ # @yield [bigquery_config] a block for modifying the bigquery configuration
312
+ # @yieldparam [Google::Cloud::PubSub::V1::BigQueryConfig] bigquery_config
313
+ #
314
+ # @return [Google::Cloud::PubSub::V1::BigQueryConfig]
315
+ #
316
+ # @example
317
+ # require "google/cloud/pubsub"
318
+ #
319
+ # pubsub = Google::Cloud::PubSub.new
320
+ #
321
+ # sub = pubsub.subscription "my-topic-sub"
322
+ # sub.bigquery_config.table #=> "my-project:dataset-id.table-id"
323
+ # sub.bigquery_config.use_topic_schema #=> true
324
+ # sub.bigquery_config.write_metadata #=> false
325
+ #
326
+ # @example Update the bigquery configuration by passing a block:
327
+ # require "google/cloud/pubsub"
328
+ #
329
+ # pubsub = Google::Cloud::PubSub.new
330
+ # sub = pubsub.subscription "my-subscription"
331
+ #
332
+ # sub.bigquery_config do |bc|
333
+ # bc.write_metadata = true
334
+ # bc.use_topic_schema = false
335
+ # end
336
+ #
337
+ def bigquery_config
338
+ ensure_service!
339
+
340
+ config = reference? ? Google::Cloud::PubSub::V1::BigQueryConfig.new : @grpc.bigquery_config
341
+
342
+ if block_given?
343
+ old_config = config.dup
344
+ yield config
345
+ new_config = config
346
+
347
+ if old_config != new_config # has the object been changed?
348
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, bigquery_config: new_config
349
+ @grpc = service.update_subscription update_grpc, :bigquery_config
350
+ end
351
+ end
352
+
353
+ config.freeze
354
+ end
355
+
283
356
  ##
284
357
  # A hash of user-provided labels associated with this subscription.
285
358
  # Labels can be used to organize and group subscriptions.See [Creating
@@ -312,8 +385,7 @@ module Google
312
385
  #
313
386
  def labels= new_labels
314
387
  raise ArgumentError, "Value must be a Hash" if new_labels.nil?
315
- update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
316
- name: name, labels: new_labels
388
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, labels: new_labels
317
389
  @grpc = service.update_subscription update_grpc, :labels
318
390
  @resource_name = nil
319
391
  end
@@ -327,7 +399,7 @@ module Google
327
399
  # If {#expires_in=} is not set, a *default* value of of 31 days will be
328
400
  # used. The minimum allowed value is 1 day.
329
401
  #
330
- # Makes an API call to retrieve the labels value when called on a
402
+ # Makes an API call to retrieve the expires_in value when called on a
331
403
  # reference object. See {#reference?}.
332
404
  #
333
405
  # @return [Numeric, nil] The expiration duration, or `nil` if unset.
@@ -350,16 +422,310 @@ module Google
350
422
  # to unset.
351
423
  #
352
424
  def expires_in= ttl
353
- new_expiration_policy = Google::Pubsub::V1::ExpirationPolicy.new(
354
- ttl: Convert.number_to_duration(ttl)
355
- )
425
+ new_expiration_policy = Google::Cloud::PubSub::V1::ExpirationPolicy.new ttl: Convert.number_to_duration(ttl)
356
426
 
357
- update_grpc = Google::Cloud::PubSub::V1::Subscription.new \
358
- name: name, expiration_policy: new_expiration_policy
427
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, expiration_policy: new_expiration_policy
359
428
  @grpc = service.update_subscription update_grpc, :expiration_policy
360
429
  @resource_name = nil
361
430
  end
362
431
 
432
+ ##
433
+ # An expression written in the Cloud Pub/Sub filter language. If non-empty, then only {Message} instances whose
434
+ # `attributes` field matches the filter are delivered on this subscription. If empty, then no messages are
435
+ # filtered out.
436
+ #
437
+ # Makes an API call to retrieve the filter value when called on a reference
438
+ # object. See {#reference?}.
439
+ #
440
+ # @return [String] The frozen filter string.
441
+ #
442
+ def filter
443
+ ensure_grpc!
444
+ @grpc.filter.freeze
445
+ end
446
+
447
+ ##
448
+ # Returns the {Topic} to which dead letter messages should be published if a dead letter policy is configured,
449
+ # otherwise `nil`. Dead lettering is done on a best effort basis. The same message might be dead lettered
450
+ # multiple times.
451
+ #
452
+ # See also {#dead_letter_topic=}, {#dead_letter_max_delivery_attempts=}, {#dead_letter_max_delivery_attempts}
453
+ # and {#remove_dead_letter_policy}.
454
+ #
455
+ # Makes an API call to retrieve the topic name when called on a reference object. See {#reference?}.
456
+ #
457
+ # @return [Topic, nil]
458
+ #
459
+ # @example
460
+ # require "google/cloud/pubsub"
461
+ #
462
+ # pubsub = Google::Cloud::PubSub.new
463
+ #
464
+ # sub = pubsub.subscription "my-topic-sub"
465
+ # sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
466
+ # sub.dead_letter_max_delivery_attempts #=> 10
467
+ #
468
+ def dead_letter_topic
469
+ ensure_grpc!
470
+ return nil unless @grpc.dead_letter_policy
471
+ Topic.from_name @grpc.dead_letter_policy.dead_letter_topic, service
472
+ end
473
+
474
+ ##
475
+ # Sets the {Topic} to which dead letter messages for the subscription should be published. Dead lettering is
476
+ # done on a best effort basis. The same message might be dead lettered multiple times.
477
+ # The Cloud Pub/Sub service account associated with the enclosing subscription's parent project (i.e.,
478
+ # `service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to this
479
+ # topic.
480
+ #
481
+ # The operation will fail if the topic does not exist. Users should ensure that there is a subscription attached
482
+ # to this topic since messages published to a topic with no subscriptions are lost.
483
+ #
484
+ # Makes an API call to retrieve the dead_letter_policy value when called on a
485
+ # reference object. See {#reference?}.
486
+ #
487
+ # See also {#dead_letter_topic}, {#dead_letter_max_delivery_attempts=}, {#dead_letter_max_delivery_attempts}
488
+ # and {#remove_dead_letter_policy}.
489
+ #
490
+ # @param [Topic] new_dead_letter_topic The topic to which dead letter messages for the subscription should be
491
+ # published.
492
+ #
493
+ # @example
494
+ # require "google/cloud/pubsub"
495
+ #
496
+ # pubsub = Google::Cloud::PubSub.new
497
+ #
498
+ # sub = pubsub.subscription "my-topic-sub"
499
+ # dead_letter_topic = pubsub.topic "my-dead-letter-topic", skip_lookup: true
500
+ # sub.dead_letter_topic = dead_letter_topic
501
+ #
502
+ def dead_letter_topic= new_dead_letter_topic
503
+ ensure_grpc!
504
+ dead_letter_policy = @grpc.dead_letter_policy || Google::Cloud::PubSub::V1::DeadLetterPolicy.new
505
+ dead_letter_policy.dead_letter_topic = new_dead_letter_topic.name
506
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, dead_letter_policy: dead_letter_policy
507
+ @grpc = service.update_subscription update_grpc, :dead_letter_policy
508
+ @resource_name = nil
509
+ end
510
+
511
+ ##
512
+ # Returns the maximum number of delivery attempts for any message in the subscription's dead letter policy if a
513
+ # dead letter policy is configured, otherwise `nil`. Dead lettering is done on a best effort basis. The same
514
+ # message might be dead lettered multiple times. The value must be between 5 and 100.
515
+ #
516
+ # The number of delivery attempts is defined as 1 + (the sum of number of NACKs and number of times the
517
+ # acknowledgement deadline has been exceeded for the message). A NACK is any call to ModifyAckDeadline with a 0
518
+ # deadline. Note that client libraries may automatically extend ack_deadlines.
519
+ #
520
+ # This field will be honored on a best effort basis. If this parameter is `nil` or `0`, a default value of `5`
521
+ # is used.
522
+ #
523
+ # See also {#dead_letter_max_delivery_attempts=}, {#dead_letter_topic=}, {#dead_letter_topic}
524
+ # and {#remove_dead_letter_policy}.
525
+ #
526
+ # Makes an API call to retrieve the dead_letter_policy when called on a reference object. See {#reference?}.
527
+ #
528
+ # @return [Integer, nil] A value between `5` and `100`, or `nil` if no dead letter policy is configured.
529
+ #
530
+ # @example
531
+ # require "google/cloud/pubsub"
532
+ #
533
+ # pubsub = Google::Cloud::PubSub.new
534
+ #
535
+ # sub = pubsub.subscription "my-topic-sub"
536
+ # sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
537
+ # sub.dead_letter_max_delivery_attempts #=> 10
538
+ #
539
+ def dead_letter_max_delivery_attempts
540
+ ensure_grpc!
541
+ @grpc.dead_letter_policy&.max_delivery_attempts
542
+ end
543
+
544
+ ##
545
+ # Sets the maximum number of delivery attempts for any message in the subscription's dead letter policy.
546
+ # Dead lettering is done on a best effort basis. The same message might be dead lettered multiple times.
547
+ # The value must be between 5 and 100.
548
+ #
549
+ # The number of delivery attempts is defined as 1 + (the sum of number of NACKs and number of times the
550
+ # acknowledgement deadline has been exceeded for the message). A NACK is any call to ModifyAckDeadline with a 0
551
+ # deadline. Note that client libraries may automatically extend ack_deadlines.
552
+ #
553
+ # This field will be honored on a best effort basis. If this parameter is 0, a default value of 5 is used.
554
+ #
555
+ # Makes an API call to retrieve the dead_letter_policy when called on a reference object. See {#reference?}.
556
+ #
557
+ # The dead letter topic must be set first. See {#dead_letter_topic=}, {#dead_letter_topic} and
558
+ # {#remove_dead_letter_policy}.
559
+ #
560
+ # @param [Integer, nil] new_dead_letter_max_delivery_attempts A value between 5 and 100. If this parameter is
561
+ # `nil` or `0`, a default value of 5 is used.
562
+ #
563
+ # @raise [ArgumentError] if the dead letter topic has not been set. See {#dead_letter_topic=}.
564
+ #
565
+ # @example
566
+ # require "google/cloud/pubsub"
567
+ #
568
+ # pubsub = Google::Cloud::PubSub.new
569
+ #
570
+ # sub = pubsub.subscription "my-topic-sub"
571
+ # sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
572
+ #
573
+ # sub.dead_letter_max_delivery_attempts = 20
574
+ #
575
+ def dead_letter_max_delivery_attempts= new_dead_letter_max_delivery_attempts
576
+ ensure_grpc!
577
+ unless @grpc.dead_letter_policy&.dead_letter_topic
578
+ # Service error message "3:Invalid resource name given (name=)." does not identify param.
579
+ raise ArgumentError, "dead_letter_topic is required with dead_letter_max_delivery_attempts"
580
+ end
581
+ dead_letter_policy = @grpc.dead_letter_policy || Google::Cloud::PubSub::V1::DeadLetterPolicy.new
582
+ dead_letter_policy.max_delivery_attempts = new_dead_letter_max_delivery_attempts
583
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, dead_letter_policy: dead_letter_policy
584
+ @grpc = service.update_subscription update_grpc, :dead_letter_policy
585
+ @resource_name = nil
586
+ end
587
+
588
+ ##
589
+ # Removes an existing dead letter policy. A dead letter policy specifies the conditions for dead lettering
590
+ # messages in the subscription. If a dead letter policy is not set, dead lettering is disabled.
591
+ #
592
+ # Makes an API call to retrieve the dead_letter_policy when called on a reference object. See {#reference?}.
593
+ #
594
+ # See {#dead_letter_topic}, {#dead_letter_topic=}, {#dead_letter_max_delivery_attempts} and
595
+ # {#dead_letter_max_delivery_attempts=}.
596
+ #
597
+ # @return [Boolean] `true` if an existing dead letter policy was removed, `false` if no existing dead letter
598
+ # policy was present.
599
+ #
600
+ # @example
601
+ # require "google/cloud/pubsub"
602
+ #
603
+ # pubsub = Google::Cloud::PubSub.new
604
+ #
605
+ # sub = pubsub.subscription "my-topic-sub"
606
+ #
607
+ # sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
608
+ # sub.dead_letter_max_delivery_attempts #=> 10
609
+ #
610
+ # sub.remove_dead_letter_policy
611
+ #
612
+ # sub.dead_letter_topic #=> nil
613
+ # sub.dead_letter_max_delivery_attempts #=> nil
614
+ #
615
+ def remove_dead_letter_policy
616
+ ensure_grpc!
617
+ return false if @grpc.dead_letter_policy.nil?
618
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, dead_letter_policy: nil
619
+ @grpc = service.update_subscription update_grpc, :dead_letter_policy
620
+ true
621
+ end
622
+
623
+ ##
624
+ # A policy that specifies how Cloud Pub/Sub retries message delivery for this subscription. If `nil`, the
625
+ # default retry policy is applied. This generally implies that messages will be retried as soon as possible
626
+ # for healthy subscribers. Retry Policy will be triggered on NACKs or acknowledgement deadline exceeded events
627
+ # for a given message.
628
+ #
629
+ # Makes an API call to retrieve the retry_policy when called on a reference object. See {#reference?}.
630
+ #
631
+ # @return [RetryPolicy, nil] The retry policy for the subscription, or `nil`.
632
+ #
633
+ # @example
634
+ # require "google/cloud/pubsub"
635
+ #
636
+ # pubsub = Google::Cloud::PubSub.new
637
+ #
638
+ # sub = pubsub.subscription "my-topic-sub"
639
+ #
640
+ # sub.retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
641
+ #
642
+ # sub.retry_policy.minimum_backoff #=> 5
643
+ # sub.retry_policy.maximum_backoff #=> 300
644
+ #
645
+ def retry_policy
646
+ ensure_grpc!
647
+ return nil unless @grpc.retry_policy
648
+ RetryPolicy.from_grpc @grpc.retry_policy
649
+ end
650
+
651
+ ##
652
+ # Sets a policy that specifies how Cloud Pub/Sub retries message delivery for this subscription. If `nil`, the
653
+ # default retry policy is applied. This generally implies that messages will be retried as soon as possible
654
+ # for healthy subscribers. Retry Policy will be triggered on NACKs or acknowledgement deadline exceeded events
655
+ # for a given message.
656
+ #
657
+ # @param [RetryPolicy, nil] new_retry_policy A new retry policy for the subscription, or `nil`.
658
+ #
659
+ # @example
660
+ # require "google/cloud/pubsub"
661
+ #
662
+ # pubsub = Google::Cloud::PubSub.new
663
+ #
664
+ # sub = pubsub.subscription "my-topic-sub"
665
+ #
666
+ # sub.retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
667
+ #
668
+ # sub.retry_policy.minimum_backoff #=> 5
669
+ # sub.retry_policy.maximum_backoff #=> 300
670
+ #
671
+ def retry_policy= new_retry_policy
672
+ ensure_service!
673
+ new_retry_policy = new_retry_policy.to_grpc if new_retry_policy
674
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, retry_policy: new_retry_policy
675
+ @grpc = service.update_subscription update_grpc, :retry_policy
676
+ @resource_name = nil
677
+ end
678
+
679
+ ##
680
+ # Whether message ordering has been enabled. When enabled, messages
681
+ # published with the same `ordering_key` will be delivered in the order
682
+ # they were published. When disabled, messages may be delivered in any
683
+ # order.
684
+ #
685
+ # @note At the time of this release, ordering keys are not yet publicly
686
+ # enabled and requires special project enablements.
687
+ #
688
+ # See {Topic#publish_async}, {#listen}, and {Message#ordering_key}.
689
+ #
690
+ # Makes an API call to retrieve the enable_message_ordering value when called on a
691
+ # reference object. See {#reference?}.
692
+ #
693
+ # @return [Boolean]
694
+ #
695
+ def message_ordering?
696
+ ensure_grpc!
697
+ @grpc.enable_message_ordering
698
+ end
699
+
700
+ ##
701
+ # Whether the subscription is detached from its topic. Detached subscriptions don't receive messages from their
702
+ # topic and don't retain any backlog. {#pull} and {#listen} (pull and streaming pull) operations will raise
703
+ # `FAILED_PRECONDITION`. If the subscription is a push subscription (see {#push_config}), pushes to the endpoint
704
+ # will not be made. The default value is `false`.
705
+ #
706
+ # See {Topic#subscribe} and {#detach}.
707
+ #
708
+ # Makes an API call to retrieve the detached value when called on a
709
+ # reference object. See {#reference?}.
710
+ #
711
+ # @return [Boolean]
712
+ #
713
+ # @example
714
+ # require "google/cloud/pubsub"
715
+ #
716
+ # pubsub = Google::Cloud::PubSub.new
717
+ #
718
+ # sub = pubsub.subscription "my-topic-sub"
719
+ # sub.detach
720
+ #
721
+ # # sleep 120
722
+ # sub.detached? #=> true
723
+ #
724
+ def detached?
725
+ ensure_grpc!
726
+ @grpc.detached
727
+ end
728
+
363
729
  ##
364
730
  # Determines whether the subscription exists in the Pub/Sub service.
365
731
  #
@@ -408,19 +774,54 @@ module Google
408
774
  end
409
775
 
410
776
  ##
411
- # Pulls messages from the server. Returns an empty list if there are no
412
- # messages available in the backlog. Raises an ApiError with status
413
- # `UNAVAILABLE` if there are too many concurrent pull requests pending
414
- # for the given subscription.
777
+ # Detaches a subscription from its topic. All messages retained in the subscription are dropped. Detached
778
+ # subscriptions don't receive messages from their topic and don't retain any backlog. Subsequent {#pull} and
779
+ # {#listen} (pull and streaming pull) operations will raise `FAILED_PRECONDITION`. If the subscription is a push
780
+ # subscription (see {#push_config}), pushes to the endpoint will stop. It may take a few minutes for the
781
+ # subscription's detached state to be reflected in subsequent calls to {#detached?}.
782
+ #
783
+ # @return [Boolean] Returns `true` if the detach operation was successful.
784
+ #
785
+ # @example
786
+ # require "google/cloud/pubsub"
787
+ #
788
+ # pubsub = Google::Cloud::PubSub.new
789
+ #
790
+ # sub = pubsub.subscription "my-topic-sub"
791
+ # sub.detach
792
+ #
793
+ # # sleep 120
794
+ # sub.detached? #=> true
795
+ #
796
+ def detach
797
+ ensure_service!
798
+ service.detach_subscription name
799
+ true
800
+ end
801
+
802
+ ##
803
+ # Pulls messages from the server, blocking until messages are available
804
+ # when called with the `immediate: false` option, which is recommended
805
+ # to avoid adverse impacts on the performance of pull operations.
806
+ #
807
+ # Raises an API error with status `UNAVAILABLE` if there are too many
808
+ # concurrent pull requests pending for the given subscription.
415
809
  #
416
810
  # See also {#listen} for the preferred way to process messages as they
417
811
  # become available.
418
812
  #
419
- # @param [Boolean] immediate When `true` the system will respond
420
- # immediately even if it is not able to return messages. When `false`
421
- # the system is allowed to wait until it can return least one message.
422
- # No messages are returned when a request times out. The default value
423
- # is `true`.
813
+ # @param [Boolean] immediate Whether to return immediately or block until
814
+ # messages are available.
815
+ #
816
+ # **Warning:** The default value of this field is `true`. However, sending
817
+ # `true` is discouraged because it adversely impacts the performance of
818
+ # pull operations. We recommend that users always explicitly set this field
819
+ # to `false`.
820
+ #
821
+ # If this field set to `true`, the system will respond immediately
822
+ # even if it there are no messages available to return in the pull
823
+ # response. Otherwise, the system may wait (for a bounded amount of time)
824
+ # until at least one message is available, rather than returning no messages.
424
825
  #
425
826
  # See also {#listen} for the preferred way to process messages as they
426
827
  # become available.
@@ -430,31 +831,24 @@ module Google
430
831
  #
431
832
  # @return [Array<Google::Cloud::PubSub::ReceivedMessage>]
432
833
  #
433
- # @example
834
+ # @example The `immediate: false` option is now recommended to avoid adverse impacts on pull operations:
434
835
  # require "google/cloud/pubsub"
435
836
  #
436
837
  # pubsub = Google::Cloud::PubSub.new
437
838
  #
438
839
  # sub = pubsub.subscription "my-topic-sub"
439
- # sub.pull.each { |received_message| received_message.acknowledge! }
440
- #
441
- # @example A maximum number of messages returned can also be specified:
442
- # require "google/cloud/pubsub"
443
- #
444
- # pubsub = Google::Cloud::PubSub.new
445
- #
446
- # sub = pubsub.subscription "my-topic-sub"
447
- # sub.pull(max: 10).each do |received_message|
840
+ # received_messages = sub.pull immediate: false
841
+ # received_messages.each do |received_message|
448
842
  # received_message.acknowledge!
449
843
  # end
450
844
  #
451
- # @example The call can block until messages are available:
845
+ # @example A maximum number of messages returned can also be specified:
452
846
  # require "google/cloud/pubsub"
453
847
  #
454
848
  # pubsub = Google::Cloud::PubSub.new
455
849
  #
456
850
  # sub = pubsub.subscription "my-topic-sub"
457
- # received_messages = sub.pull immediate: false
851
+ # received_messages = sub.pull immediate: false, max: 10
458
852
  # received_messages.each do |received_message|
459
853
  # received_message.acknowledge!
460
854
  # end
@@ -508,17 +902,60 @@ module Google
508
902
  # message will be removed from the subscriber and made available for
509
903
  # redelivery after the callback is completed.
510
904
  #
905
+ # Google Cloud Pub/Sub ordering keys provide the ability to ensure
906
+ # related messages are sent to subscribers in the order in which they
907
+ # were published. Messages can be tagged with an ordering key, a string
908
+ # that identifies related messages for which publish order should be
909
+ # respected. The service guarantees that, for a given ordering key and
910
+ # publisher, messages are sent to subscribers in the order in which they
911
+ # were published. Ordering does not require sacrificing high throughput
912
+ # or scalability, as the service automatically distributes messages for
913
+ # different ordering keys across subscribers.
914
+ #
915
+ # To use ordering keys, the subscription must be created with message
916
+ # ordering enabled (See {Topic#subscribe} and {#message_ordering?})
917
+ # before calling {#listen}. When enabled, the subscriber will deliver
918
+ # messages with the same `ordering_key` in the order they were
919
+ # published.
920
+ #
921
+ # @note At the time of this release, ordering keys are not yet publicly
922
+ # enabled and requires special project enablements.
923
+ #
511
924
  # @param [Numeric] deadline The default number of seconds the stream
512
925
  # will hold received messages before modifying the message's ack
513
926
  # deadline. The minimum is 10, the maximum is 600. Default is
514
927
  # {#deadline}. Optional.
515
928
  #
516
- # Makes an API call to retrieve the deadline value when called on a
517
- # reference object. See {#reference?}.
929
+ # When using a reference object an API call will be made to retrieve
930
+ # the default deadline value for the subscription when this argument
931
+ # is not provided. See {#reference?}.
932
+ # @param [Boolean] message_ordering Whether message ordering has been
933
+ # enabled. The value provided must match the value set on the Pub/Sub
934
+ # service. See {#message_ordering?}. Optional.
935
+ #
936
+ # When using a reference object an API call will be made to retrieve
937
+ # the default message_ordering value for the subscription when this
938
+ # argument is not provided. See {#reference?}.
518
939
  # @param [Integer] streams The number of concurrent streams to open to
519
- # pull messages from the subscription. Default is 4. Optional.
520
- # @param [Integer] inventory The number of received messages to be
521
- # collected by subscriber. Default is 1,000. Optional.
940
+ # pull messages from the subscription. Default is 2. Optional.
941
+ # @param [Hash, Integer] inventory The settings to control how received messages are to be handled by the
942
+ # subscriber. When provided as an Integer instead of a Hash only `max_outstanding_messages` will be set.
943
+ # Optional.
944
+ #
945
+ # Hash keys and values may include the following:
946
+ #
947
+ # * `:max_outstanding_messages` [Integer] The number of received messages to be collected by subscriber.
948
+ # Default is 1,000. (Note: replaces `:limit`, which is deprecated.)
949
+ # * `:max_outstanding_bytes` [Integer] The total byte size of received messages to be collected by
950
+ # subscriber. Default is 100,000,000 (100MB). (Note: replaces `:bytesize`, which is deprecated.)
951
+ # * `:use_legacy_flow_control` [Boolean] Disables enforcing flow control settings at the Cloud PubSub
952
+ # server and the less accurate method of only enforcing flow control at the client side is used instead.
953
+ # Default is false.
954
+ # * `:max_total_lease_duration` [Integer] The number of seconds that received messages can be held awaiting
955
+ # processing. Default is 3,600 (1 hour). (Note: replaces `:extension`, which is deprecated.)
956
+ # * `:max_duration_per_lease_extension` [Integer] The maximum amount of time in seconds for a single lease
957
+ # extension attempt. Bounds the delay before a message redelivery if the subscriber fails to extend the
958
+ # deadline. Default is 0 (disabled).
522
959
  # @param [Hash] threads The number of threads to create to handle
523
960
  # concurrent calls by each stream opened by the subscriber. Optional.
524
961
  #
@@ -546,6 +983,7 @@ module Google
546
983
  #
547
984
  # subscriber = sub.listen do |received_message|
548
985
  # # process message
986
+ # puts "Data: #{received_message.message.data}, published at #{received_message.message.published_at}"
549
987
  # received_message.acknowledge!
550
988
  # end
551
989
  #
@@ -553,7 +991,7 @@ module Google
553
991
  # subscriber.start
554
992
  #
555
993
  # # Shut down the subscriber when ready to stop receiving messages.
556
- # subscriber.stop.wait!
994
+ # subscriber.stop!
557
995
  #
558
996
  # @example Configuring to increase concurrent callbacks:
559
997
  # require "google/cloud/pubsub"
@@ -571,14 +1009,55 @@ module Google
571
1009
  # # Start background threads that will call block passed to listen.
572
1010
  # subscriber.start
573
1011
  #
574
- def listen deadline: nil, streams: nil, inventory: nil, threads: {},
575
- &block
1012
+ # # Shut down the subscriber when ready to stop receiving messages.
1013
+ # subscriber.stop!
1014
+ #
1015
+ # @example Ordered messages are supported using ordering_key:
1016
+ # require "google/cloud/pubsub"
1017
+ #
1018
+ # pubsub = Google::Cloud::PubSub.new
1019
+ #
1020
+ # sub = pubsub.subscription "my-ordered-topic-sub"
1021
+ # sub.message_ordering? #=> true
1022
+ #
1023
+ # subscriber = sub.listen do |received_message|
1024
+ # # messsages with the same ordering_key are received
1025
+ # # in the order in which they were published.
1026
+ # received_message.acknowledge!
1027
+ # end
1028
+ #
1029
+ # # Start background threads that will call block passed to listen.
1030
+ # subscriber.start
1031
+ #
1032
+ # # Shut down the subscriber when ready to stop receiving messages.
1033
+ # subscriber.stop!
1034
+ #
1035
+ # @example Set the maximum amount of time before redelivery if the subscriber fails to extend the deadline:
1036
+ # require "google/cloud/pubsub"
1037
+ #
1038
+ # pubsub = Google::Cloud::PubSub.new
1039
+ #
1040
+ # sub = pubsub.subscription "my-topic-sub"
1041
+ #
1042
+ # subscriber = sub.listen inventory: { max_duration_per_lease_extension: 20 } do |received_message|
1043
+ # # Process message very slowly with possibility of failure.
1044
+ # process rec_message.data # takes minutes
1045
+ # rec_message.acknowledge!
1046
+ # end
1047
+ #
1048
+ # # Start background threads that will call block passed to listen.
1049
+ # subscriber.start
1050
+ #
1051
+ # # Shut down the subscriber when ready to stop receiving messages.
1052
+ # subscriber.stop!
1053
+ #
1054
+ def listen deadline: nil, message_ordering: nil, streams: nil, inventory: nil, threads: {}, &block
576
1055
  ensure_service!
577
1056
  deadline ||= self.deadline
1057
+ message_ordering = message_ordering? if message_ordering.nil?
578
1058
 
579
- Subscriber.new name, block, deadline: deadline, streams: streams,
580
- inventory: inventory, threads: threads,
581
- service: service
1059
+ Subscriber.new name, block, deadline: deadline, streams: streams, inventory: inventory,
1060
+ message_ordering: message_ordering, threads: threads, service: service
582
1061
  end
583
1062
 
584
1063
  ##
@@ -600,7 +1079,7 @@ module Google
600
1079
  # pubsub = Google::Cloud::PubSub.new
601
1080
  #
602
1081
  # sub = pubsub.subscription "my-topic-sub"
603
- # received_messages = sub.pull
1082
+ # received_messages = sub.pull immediate: false
604
1083
  # sub.acknowledge received_messages
605
1084
  #
606
1085
  def acknowledge *messages
@@ -635,7 +1114,7 @@ module Google
635
1114
  # pubsub = Google::Cloud::PubSub.new
636
1115
  #
637
1116
  # sub = pubsub.subscription "my-topic-sub"
638
- # received_messages = sub.pull
1117
+ # received_messages = sub.pull immediate: false
639
1118
  # sub.modify_ack_deadline 120, received_messages
640
1119
  #
641
1120
  def modify_ack_deadline new_deadline, *messages
@@ -656,14 +1135,19 @@ module Google
656
1135
  # * Any messages published to the subscription's topic following the
657
1136
  # successful completion of the `create_snapshot` operation.
658
1137
  #
659
- # @param [String, nil] snapshot_name Name of the new snapshot. If the
660
- # name is not provided, the server will assign a random name
661
- # for this snapshot on the same project as the subscription. The
662
- # format is `projects/{project}/snapshots/{snap}`. The name must start
663
- # with a letter, and contain only letters ([A-Za-z]), numbers
664
- # ([0-9], dashes (-), underscores (_), periods (.), tildes (~), plus
665
- # (+) or percent signs (%). It must be between 3 and 255 characters in
666
- # length, and it must not start with "goog". Optional.
1138
+ # @param [String, nil] snapshot_name Name of the new snapshot. Optional.
1139
+ # If the name is not provided, the server will assign a random name
1140
+ # for this snapshot on the same project as the subscription.
1141
+ # The value can be a simple snapshot ID (relative name), in which
1142
+ # case the current project ID will be supplied, or a fully-qualified
1143
+ # snapshot name in the form
1144
+ # `projects/{project_id}/snapshots/{snapshot_id}`.
1145
+ #
1146
+ # The snapshot ID (relative name) must start with a letter, and
1147
+ # contain only letters (`[A-Za-z]`), numbers (`[0-9]`), dashes (`-`),
1148
+ # underscores (`_`), periods (`.`), tildes (`~`), plus (`+`) or percent
1149
+ # signs (`%`). It must be between 3 and 255 characters in length, and
1150
+ # it must not start with `goog`.
667
1151
  # @param [Hash] labels A hash of user-provided labels associated with
668
1152
  # the snapshot. You can use these to organize and group your
669
1153
  # snapshots. Label keys and values can be no longer than 63
@@ -728,7 +1212,7 @@ module Google
728
1212
  #
729
1213
  # snapshot = sub.create_snapshot
730
1214
  #
731
- # received_messages = sub.pull
1215
+ # received_messages = sub.pull immediate: false
732
1216
  # sub.acknowledge received_messages
733
1217
  #
734
1218
  # sub.seek snapshot
@@ -741,7 +1225,7 @@ module Google
741
1225
  #
742
1226
  # time = Time.now
743
1227
  #
744
- # received_messages = sub.pull
1228
+ # received_messages = sub.pull immediate: false
745
1229
  # sub.acknowledge received_messages
746
1230
  #
747
1231
  # sub.seek time