google-cloud-pubsub 1.2.2 → 1.3.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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 6eb38845984e78d2c7f5e3fb376e7e384323c08ed6e1ed03dc341f6936577a5a
4
- data.tar.gz: 6530343d9396bbf325cd7a9667a3e0e185063a9fcc42c81e522d83c82c83ec5e
3
+ metadata.gz: f176e0d099e688edae5273450671e309a2ddd9a34ff6845a29dcbe972e452aba
4
+ data.tar.gz: 47cf3c8e40d728c48c306646381e0d3024bd95f8986675aae285c929a7ebffb0
5
5
  SHA512:
6
- metadata.gz: e3ae4aa5ba8c61842a62eedb7ac896bedfddff137603a3c49948a094cd335ab5d0879aeeca0f59be0c7e4729e34fd71352751dbd2946118e7d5a7c6893afd568
7
- data.tar.gz: b7236c32fca695dc77d35813c5acdd62375c575c8ccf1e1568d39e79ccdc6a6f16604008f81dcecb64ec6ab91ecf4666b35c7428a9e06eeacf7cd5c054f00e97
6
+ metadata.gz: 5df91b44a3f0bcb2ec096fa49b6bac50b04af7e8cb4e6896a1d4be456663f5f009690ff37b875664e04c55a55bb84acb06c55c2dfacec290672746da071e93be
7
+ data.tar.gz: 363d70b5b69b06169afc5256d83c8f8f62b2fea532bd612d37ded55114f0f421bd978f13cf5329be3ca481bd059f853143705d9aa2ca00cf27cba032b63135f2
@@ -1,5 +1,15 @@
1
1
  # Release History
2
2
 
3
+ ### 1.3.0 / 2020-02-10
4
+
5
+ #### Features
6
+
7
+ * Add support for Dead Letter Topics
8
+ * Add `dead_letter_topic` and `dead_letter_max_delivery_attempts` to `Topic#subscribe`
9
+ * Add `Subscription#dead_letter_topic` and `Subscription#dead_letter_topic=`
10
+ * Add `Subscription#dead_letter_max_delivery_attempts` and `Subscription#dead_letter_max_delivery_attempts=`
11
+ * Add `ReceivedMessage#delivery_attempt`
12
+
3
13
  ### 1.2.2 / 2020-02-04
4
14
 
5
15
  #### Performance Improvements
@@ -63,6 +63,49 @@ module Google
63
63
  @grpc.ack_id
64
64
  end
65
65
 
66
+ ##
67
+ # Returns the delivery attempt counter for the message. If a dead letter policy is not set on the subscription,
68
+ # this will be `nil`. See {Topic#subscribe}, {Subscription#dead_letter_topic=} and
69
+ # {Subscription#dead_letter_max_delivery_attempts=}.
70
+ #
71
+ # The delivery attempt counter is `1 + (the sum of number of NACKs and number of ack_deadline exceeds)` for the
72
+ # message.
73
+ #
74
+ # A NACK is any call to `ModifyAckDeadline` with a `0` deadline. An `ack_deadline` exceeds event is whenever a
75
+ # message is not acknowledged within `ack_deadline`. Note that `ack_deadline` is initially
76
+ # `Subscription.ackDeadlineSeconds`, but may get extended automatically by the client library.
77
+ #
78
+ # The first delivery of a given message will have this value as `1`. The value is calculated at best effort and
79
+ # is approximate.
80
+ #
81
+ # EXPERIMENTAL: This feature is part of a closed alpha release and is available only to whitelisted partners.
82
+ # This method will return `nil` if a dead letter policy is not set on the subscription. This API might be
83
+ # changed in backward-incompatible ways and is not recommended for production use. It is not subject to any SLA
84
+ # or deprecation policy.
85
+ #
86
+ # @return [Integer, nil] A delivery attempt value of `1` or greater, or `nil` if a dead letter policy is not set
87
+ # on the subscription.
88
+ #
89
+ # @example
90
+ # require "google/cloud/pubsub"
91
+ #
92
+ # pubsub = Google::Cloud::PubSub.new
93
+ #
94
+ # topic = pubsub.topic "my-topic"
95
+ # dead_letter_topic = pubsub.topic "my-dead-letter-topic", skip_lookup: true
96
+ # sub = topic.subscribe "my-topic-sub",
97
+ # dead_letter_topic: dead_letter_topic,
98
+ # dead_letter_max_delivery_attempts: 10
99
+ #
100
+ # subscriber = sub.listen do |received_message|
101
+ # puts received_message.message.delivery_attempt
102
+ # end
103
+ #
104
+ def delivery_attempt
105
+ return nil if @grpc.delivery_attempt && @grpc.delivery_attempt < 1
106
+ @grpc.delivery_attempt
107
+ end
108
+
66
109
  ##
67
110
  # The received message.
68
111
  def message
@@ -238,7 +238,6 @@ module Google
238
238
  mrd = Convert.number_to_duration options[:retention]
239
239
  labels = options[:labels]
240
240
  message_ordering = options[:message_ordering]
241
-
242
241
  execute do
243
242
  subscriber.create_subscription \
244
243
  name, topic,
@@ -248,6 +247,7 @@ module Google
248
247
  message_retention_duration: mrd,
249
248
  labels: labels,
250
249
  enable_message_ordering: message_ordering,
250
+ dead_letter_policy: dead_letter_policy(options),
251
251
  options: default_options
252
252
  end
253
253
  end
@@ -477,6 +477,15 @@ module Google
477
477
  true
478
478
  end
479
479
 
480
+ def dead_letter_policy options
481
+ return nil unless options[:dead_letter_topic_name]
482
+ policy = Google::Cloud::PubSub::V1::DeadLetterPolicy.new dead_letter_topic: options[:dead_letter_topic_name]
483
+ if options[:dead_letter_max_delivery_attempts]
484
+ policy.max_delivery_attempts = options[:dead_letter_max_delivery_attempts]
485
+ end
486
+ policy
487
+ end
488
+
480
489
  def default_headers
481
490
  { "google-cloud-resource-prefix" => "projects/#{@project}" }
482
491
  end
@@ -20,6 +20,7 @@ require "google/cloud/pubsub/subscription/push_config"
20
20
  require "google/cloud/pubsub/received_message"
21
21
  require "google/cloud/pubsub/snapshot"
22
22
  require "google/cloud/pubsub/subscriber"
23
+ require "google/cloud/pubsub/v1"
23
24
 
24
25
  module Google
25
26
  module Cloud
@@ -351,6 +352,137 @@ module Google
351
352
  @resource_name = nil
352
353
  end
353
354
 
355
+ ##
356
+ # Returns the {Topic} to which dead letter messages should be published if a dead letter policy is configured,
357
+ # otherwise `nil`. Dead lettering is done on a best effort basis. The same message might be dead lettered
358
+ # multiple times.
359
+ #
360
+ # See also {#dead_letter_topic=}, {#dead_letter_max_delivery_attempts=} and
361
+ # {#dead_letter_max_delivery_attempts}.
362
+ #
363
+ # Makes an API call to retrieve the topic name when called on a reference object. See {#reference?}.
364
+ #
365
+ # @return [Topic, nil]
366
+ #
367
+ # @example
368
+ # require "google/cloud/pubsub"
369
+ #
370
+ # pubsub = Google::Cloud::PubSub.new
371
+ #
372
+ # sub = pubsub.subscription "my-topic-sub"
373
+ # sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
374
+ # sub.dead_letter_max_delivery_attempts #=> 10
375
+ #
376
+ def dead_letter_topic
377
+ ensure_grpc!
378
+ return nil unless @grpc.dead_letter_policy
379
+ Topic.from_name @grpc.dead_letter_policy.dead_letter_topic, service
380
+ end
381
+
382
+ ##
383
+ # Sets the {Topic} to which dead letter messages for the subscription should be published. Dead lettering is
384
+ # done on a best effort basis. The same message might be dead lettered multiple times.
385
+ # The Cloud Pub/Sub service account associated with the enclosing subscription's parent project (i.e.,
386
+ # `service-\\{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to this
387
+ # topic.
388
+ #
389
+ # The operation will fail if the topic does not exist. Users should ensure that there is a subscription attached
390
+ # to this topic since messages published to a topic with no subscriptions are lost.
391
+ #
392
+ # See also {#dead_letter_topic}, {#dead_letter_max_delivery_attempts=} and {#dead_letter_max_delivery_attempts}.
393
+ #
394
+ # @param [Topic] new_dead_letter_topic The topic to which dead letter messages for the subscription should be
395
+ # published.
396
+ #
397
+ # @example
398
+ # require "google/cloud/pubsub"
399
+ #
400
+ # pubsub = Google::Cloud::PubSub.new
401
+ #
402
+ # sub = pubsub.subscription "my-topic-sub"
403
+ # dead_letter_topic = pubsub.topic "my-dead-letter-topic", skip_lookup: true
404
+ # sub.dead_letter_topic = dead_letter_topic
405
+ #
406
+ def dead_letter_topic= new_dead_letter_topic
407
+ ensure_grpc!
408
+ dead_letter_policy = @grpc.dead_letter_policy || Google::Cloud::PubSub::V1::DeadLetterPolicy.new
409
+ dead_letter_policy.dead_letter_topic = new_dead_letter_topic.name
410
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, dead_letter_policy: dead_letter_policy
411
+ @grpc = service.update_subscription update_grpc, :dead_letter_policy
412
+ @resource_name = nil
413
+ end
414
+
415
+ ##
416
+ # Returns the maximum number of delivery attempts for any message in the subscription's dead letter policy if a
417
+ # dead letter policy is configured, otherwise `nil`. Dead lettering is done on a best effort basis. The same
418
+ # message might be dead lettered multiple times. The value must be between 5 and 100.
419
+ #
420
+ # The number of delivery attempts is defined as 1 + (the sum of number of NACKs and number of times the
421
+ # acknowledgement deadline has been exceeded for the message). A NACK is any call to ModifyAckDeadline with a 0
422
+ # deadline. Note that client libraries may automatically extend ack_deadlines.
423
+ #
424
+ # This field will be honored on a best effort basis. If this parameter is 0, a default value of 5 is used.
425
+ #
426
+ # See also {#dead_letter_max_delivery_attempts=}, {#dead_letter_topic=} and {#dead_letter_topic}.
427
+ #
428
+ # Makes an API call to retrieve the value when called on a reference object. See {#reference?}.
429
+ #
430
+ # @return [Integer, nil] A value between 5 and 100, or `nil` if no dead letter policy is configured. If this
431
+ # value is 0, a default value of 5 is used.
432
+ #
433
+ # @example
434
+ # require "google/cloud/pubsub"
435
+ #
436
+ # pubsub = Google::Cloud::PubSub.new
437
+ #
438
+ # sub = pubsub.subscription "my-topic-sub"
439
+ # sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
440
+ # sub.dead_letter_max_delivery_attempts #=> 10
441
+ #
442
+ def dead_letter_max_delivery_attempts
443
+ ensure_grpc!
444
+ @grpc.dead_letter_policy&.max_delivery_attempts
445
+ end
446
+
447
+ ##
448
+ # Sets the maximum number of delivery attempts for any message in the subscription's dead letter policy.
449
+ # Dead lettering is done on a best effort basis. The same message might be dead lettered multiple times.
450
+ # The value must be between 5 and 100.
451
+ #
452
+ # The number of delivery attempts is defined as 1 + (the sum of number of NACKs and number of times the
453
+ # acknowledgement deadline has been exceeded for the message). A NACK is any call to ModifyAckDeadline with a 0
454
+ # deadline. Note that client libraries may automatically extend ack_deadlines.
455
+ #
456
+ # This field will be honored on a best effort basis. If this parameter is 0, a default value of 5 is used.
457
+ #
458
+ # The dead letter topic must also be set. See {#dead_letter_topic=} and {#dead_letter_topic}.
459
+ #
460
+ # @param [Integer] new_dead_letter_max_delivery_attempts A value between 5 and 100. If this parameter is 0, a
461
+ # default value of 5 is used.
462
+ #
463
+ # @example
464
+ # require "google/cloud/pubsub"
465
+ #
466
+ # pubsub = Google::Cloud::PubSub.new
467
+ #
468
+ # sub = pubsub.subscription "my-topic-sub"
469
+ # sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
470
+ #
471
+ # sub.dead_letter_max_delivery_attempts = 20
472
+ #
473
+ def dead_letter_max_delivery_attempts= new_dead_letter_max_delivery_attempts
474
+ ensure_grpc!
475
+ unless @grpc.dead_letter_policy&.dead_letter_topic
476
+ # Service error message "3:Invalid resource name given (name=)." does not identify param.
477
+ raise ArgumentError, "dead_letter_topic is required with dead_letter_max_delivery_attempts"
478
+ end
479
+ dead_letter_policy = @grpc.dead_letter_policy || Google::Cloud::PubSub::V1::DeadLetterPolicy.new
480
+ dead_letter_policy.max_delivery_attempts = new_dead_letter_max_delivery_attempts
481
+ update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, dead_letter_policy: dead_letter_policy
482
+ @grpc = service.update_subscription update_grpc, :dead_letter_policy
483
+ @resource_name = nil
484
+ end
485
+
354
486
  ##
355
487
  # Whether message ordering has been enabled. When enabled, messages
356
488
  # published with the same `ordering_key` will be delivered in the order
@@ -285,6 +285,18 @@ module Google
285
285
  # Managing Labels](https://cloud.google.com/pubsub/docs/labels).
286
286
  # @param [Boolean] message_ordering Whether to enable message ordering
287
287
  # on the subscription.
288
+ # @param [Topic] dead_letter_topic The {Topic} to which dead letter messages for the subscription should be
289
+ # published. Dead lettering is done on a best effort basis. The same message might be dead lettered multiple
290
+ # times. The Cloud Pub/Sub service account associated with the enclosing subscription's parent project (i.e.,
291
+ # `service-\\{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to
292
+ # this topic.
293
+ #
294
+ # The operation will fail if the topic does not exist. Users should ensure that there is a subscription
295
+ # attached to this topic since messages published to a topic with no subscriptions are lost.
296
+ # @param [Integer] dead_letter_max_delivery_attempts The maximum number of delivery attempts for any message in
297
+ # the subscription's dead letter policy. Dead lettering is done on a best effort basis. The same message might
298
+ # be dead lettered multiple times. The value must be between 5 and 100. If this parameter is 0, a default
299
+ # value of 5 is used. The `dead_letter_topic` must also be set.
288
300
  #
289
301
  # @return [Google::Cloud::PubSub::Subscription]
290
302
  #
@@ -307,11 +319,38 @@ module Google
307
319
  # deadline: 120,
308
320
  # endpoint: "https://example.com/push"
309
321
  #
322
+ # @example Configure a Dead Letter Queues policy:
323
+ # require "google/cloud/pubsub"
324
+ #
325
+ # pubsub = Google::Cloud::PubSub.new
326
+ #
327
+ # # Dead Letter Queue (DLQ) testing requires IAM bindings to the Cloud Pub/Sub service account that is
328
+ # # automatically created and managed by the service team in a private project.
329
+ # my_project_number = "000000000000"
330
+ # service_account_email = "serviceAccount:service-#{my_project_number}@gcp-sa-pubsub.iam.gserviceaccount.com"
331
+ #
332
+ # dead_letter_topic = pubsub.topic "my-dead-letter-topic"
333
+ # dead_letter_subscription = dead_letter_topic.subscribe "my-dead-letter-sub"
334
+ #
335
+ # dead_letter_topic.policy { |p| p.add "roles/pubsub.publisher", service_account_email }
336
+ # dead_letter_subscription.policy { |p| p.add "roles/pubsub.subscriber", service_account_email }
337
+ #
338
+ # topic = pubsub.topic "my-topic"
339
+ # sub = topic.subscribe "my-topic-sub",
340
+ # dead_letter_topic: dead_letter_topic,
341
+ # dead_letter_max_delivery_attempts: 10
342
+ #
310
343
  def subscribe subscription_name, deadline: nil, retain_acked: false, retention: nil, endpoint: nil, labels: nil,
311
- message_ordering: nil
344
+ message_ordering: nil, dead_letter_topic: nil, dead_letter_max_delivery_attempts: nil
312
345
  ensure_service!
313
346
  options = { deadline: deadline, retain_acked: retain_acked, retention: retention, endpoint: endpoint,
314
- labels: labels, message_ordering: message_ordering }
347
+ labels: labels, message_ordering: message_ordering,
348
+ dead_letter_max_delivery_attempts: dead_letter_max_delivery_attempts }
349
+ options[:dead_letter_topic_name] = dead_letter_topic.name if dead_letter_topic
350
+ if options[:dead_letter_max_delivery_attempts] && !options[:dead_letter_topic_name]
351
+ # Service error message "3:Invalid resource name given (name=)." does not identify param.
352
+ raise ArgumentError, "dead_letter_topic is required with dead_letter_max_delivery_attempts"
353
+ end
315
354
  grpc = service.create_subscription name, subscription_name, options
316
355
  Subscription.from_grpc grpc, service
317
356
  end
@@ -16,7 +16,7 @@
16
16
  module Google
17
17
  module Cloud
18
18
  module PubSub
19
- VERSION = "1.2.2".freeze
19
+ VERSION = "1.3.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: 1.2.2
4
+ version: 1.3.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: 2020-02-04 00:00:00.000000000 Z
12
+ date: 2020-02-10 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: concurrent-ruby