google-cloud-pubsub 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6eb38845984e78d2c7f5e3fb376e7e384323c08ed6e1ed03dc341f6936577a5a
-  data.tar.gz: 6530343d9396bbf325cd7a9667a3e0e185063a9fcc42c81e522d83c82c83ec5e
+  metadata.gz: f176e0d099e688edae5273450671e309a2ddd9a34ff6845a29dcbe972e452aba
+  data.tar.gz: 47cf3c8e40d728c48c306646381e0d3024bd95f8986675aae285c929a7ebffb0
 SHA512:
-  metadata.gz: e3ae4aa5ba8c61842a62eedb7ac896bedfddff137603a3c49948a094cd335ab5d0879aeeca0f59be0c7e4729e34fd71352751dbd2946118e7d5a7c6893afd568
-  data.tar.gz: b7236c32fca695dc77d35813c5acdd62375c575c8ccf1e1568d39e79ccdc6a6f16604008f81dcecb64ec6ab91ecf4666b35c7428a9e06eeacf7cd5c054f00e97
+  metadata.gz: 5df91b44a3f0bcb2ec096fa49b6bac50b04af7e8cb4e6896a1d4be456663f5f009690ff37b875664e04c55a55bb84acb06c55c2dfacec290672746da071e93be
+  data.tar.gz: 363d70b5b69b06169afc5256d83c8f8f62b2fea532bd612d37ded55114f0f421bd978f13cf5329be3ca481bd059f853143705d9aa2ca00cf27cba032b63135f2

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Release History
 
+### 1.3.0 / 2020-02-10
+
+#### Features
+
+* Add support for Dead Letter Topics
+  * Add `dead_letter_topic` and `dead_letter_max_delivery_attempts` to `Topic#subscribe`
+  * Add `Subscription#dead_letter_topic` and `Subscription#dead_letter_topic=`
+  * Add `Subscription#dead_letter_max_delivery_attempts` and `Subscription#dead_letter_max_delivery_attempts=`
+  * Add `ReceivedMessage#delivery_attempt`
+
 ### 1.2.2 / 2020-02-04
 
 #### Performance Improvements

data/lib/google/cloud/pubsub/received_message.rb

@@ -63,6 +63,49 @@ module Google
           @grpc.ack_id
         end
 
+        ##
+        # Returns the delivery attempt counter for the message. If a dead letter policy is not set on the subscription,
+        # this will be `nil`. See {Topic#subscribe}, {Subscription#dead_letter_topic=} and
+        # {Subscription#dead_letter_max_delivery_attempts=}.
+        #
+        # The delivery attempt counter is `1 + (the sum of number of NACKs and number of ack_deadline exceeds)` for the
+        # message.
+        #
+        # A NACK is any call to `ModifyAckDeadline` with a `0` deadline. An `ack_deadline` exceeds event is whenever a
+        # message is not acknowledged within `ack_deadline`. Note that `ack_deadline` is initially
+        # `Subscription.ackDeadlineSeconds`, but may get extended automatically by the client library.
+        #
+        # The first delivery of a given message will have this value as `1`. The value is calculated at best effort and
+        # is approximate.
+        #
+        # EXPERIMENTAL: This feature is part of a closed alpha release and is available only to whitelisted partners.
+        # This method will return `nil` if a dead letter policy is not set on the subscription. This API might be
+        # changed in backward-incompatible ways and is not recommended for production use. It is not subject to any SLA
+        # or deprecation policy.
+        #
+        # @return [Integer, nil] A delivery attempt value of `1` or greater, or `nil` if a dead letter policy is not set
+        #   on the subscription.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   topic = pubsub.topic "my-topic"
+        #   dead_letter_topic = pubsub.topic "my-dead-letter-topic", skip_lookup: true
+        #   sub = topic.subscribe "my-topic-sub",
+        #                         dead_letter_topic: dead_letter_topic,
+        #                         dead_letter_max_delivery_attempts: 10
+        #
+        #   subscriber = sub.listen do |received_message|
+        #     puts received_message.message.delivery_attempt
+        #   end
+        #
+        def delivery_attempt
+          return nil if @grpc.delivery_attempt && @grpc.delivery_attempt < 1
+          @grpc.delivery_attempt
+        end
+
         ##
         # The received message.
         def message

data/lib/google/cloud/pubsub/service.rb

@@ -238,7 +238,6 @@ module Google
           mrd = Convert.number_to_duration options[:retention]
           labels = options[:labels]
           message_ordering = options[:message_ordering]
-
           execute do
             subscriber.create_subscription \
               name, topic,
@@ -248,6 +247,7 @@ module Google
               message_retention_duration: mrd,
               labels:                     labels,
               enable_message_ordering:    message_ordering,
+              dead_letter_policy:         dead_letter_policy(options),
               options:                    default_options
           end
         end
@@ -477,6 +477,15 @@ module Google
           true
         end
 
+        def dead_letter_policy options
+          return nil unless options[:dead_letter_topic_name]
+          policy = Google::Cloud::PubSub::V1::DeadLetterPolicy.new dead_letter_topic: options[:dead_letter_topic_name]
+          if options[:dead_letter_max_delivery_attempts]
+            policy.max_delivery_attempts = options[:dead_letter_max_delivery_attempts]
+          end
+          policy
+        end
+
         def default_headers
           { "google-cloud-resource-prefix" => "projects/#{@project}" }
         end

data/lib/google/cloud/pubsub/subscription.rb

@@ -20,6 +20,7 @@ require "google/cloud/pubsub/subscription/push_config"
 require "google/cloud/pubsub/received_message"
 require "google/cloud/pubsub/snapshot"
 require "google/cloud/pubsub/subscriber"
+require "google/cloud/pubsub/v1"
 
 module Google
   module Cloud
@@ -351,6 +352,137 @@ module Google
           @resource_name = nil
         end
 
+        ##
+        # Returns the {Topic} to which dead letter messages should be published if a dead letter policy is configured,
+        # otherwise `nil`. Dead lettering is done on a best effort basis. The same message might be dead lettered
+        # multiple times.
+        #
+        # See also {#dead_letter_topic=}, {#dead_letter_max_delivery_attempts=} and
+        # {#dead_letter_max_delivery_attempts}.
+        #
+        # Makes an API call to retrieve the topic name when called on a reference object. See {#reference?}.
+        #
+        # @return [Topic, nil]
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
+        #   sub.dead_letter_max_delivery_attempts #=> 10
+        #
+        def dead_letter_topic
+          ensure_grpc!
+          return nil unless @grpc.dead_letter_policy
+          Topic.from_name @grpc.dead_letter_policy.dead_letter_topic, service
+        end
+
+        ##
+        # Sets the {Topic} to which dead letter messages for the subscription should be published. Dead lettering is
+        # done on a best effort basis. The same message might be dead lettered multiple times.
+        # The Cloud Pub/Sub service account associated with the enclosing subscription's parent project (i.e.,
+        # `service-\\{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to this
+        # topic.
+        #
+        # The operation will fail if the topic does not exist. Users should ensure that there is a subscription attached
+        # to this topic since messages published to a topic with no subscriptions are lost.
+        #
+        # See also {#dead_letter_topic}, {#dead_letter_max_delivery_attempts=} and {#dead_letter_max_delivery_attempts}.
+        #
+        # @param [Topic] new_dead_letter_topic The topic to which dead letter messages for the subscription should be
+        #   published.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   dead_letter_topic = pubsub.topic "my-dead-letter-topic", skip_lookup: true
+        #   sub.dead_letter_topic = dead_letter_topic
+        #
+        def dead_letter_topic= new_dead_letter_topic
+          ensure_grpc!
+          dead_letter_policy = @grpc.dead_letter_policy || Google::Cloud::PubSub::V1::DeadLetterPolicy.new
+          dead_letter_policy.dead_letter_topic = new_dead_letter_topic.name
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, dead_letter_policy: dead_letter_policy
+          @grpc = service.update_subscription update_grpc, :dead_letter_policy
+          @resource_name = nil
+        end
+
+        ##
+        # Returns the maximum number of delivery attempts for any message in the subscription's dead letter policy if a
+        # dead letter policy is configured, otherwise `nil`. Dead lettering is done on a best effort basis. The same
+        # message might be dead lettered multiple times. The value must be between 5 and 100.
+        #
+        # The number of delivery attempts is defined as 1 + (the sum of number of NACKs and number of times the
+        # acknowledgement deadline has been exceeded for the message). A NACK is any call to ModifyAckDeadline with a 0
+        # deadline. Note that client libraries may automatically extend ack_deadlines.
+        #
+        # This field will be honored on a best effort basis. If this parameter is 0, a default value of 5 is used.
+        #
+        # See also {#dead_letter_max_delivery_attempts=}, {#dead_letter_topic=} and {#dead_letter_topic}.
+        #
+        # Makes an API call to retrieve the value when called on a reference object. See {#reference?}.
+        #
+        # @return [Integer, nil] A value between 5 and 100, or `nil` if no dead letter policy is configured. If this
+        #   value is 0, a default value of 5 is used.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
+        #   sub.dead_letter_max_delivery_attempts #=> 10
+        #
+        def dead_letter_max_delivery_attempts
+          ensure_grpc!
+          @grpc.dead_letter_policy&.max_delivery_attempts
+        end
+
+        ##
+        # Sets the maximum number of delivery attempts for any message in the subscription's dead letter policy.
+        # Dead lettering is done on a best effort basis. The same message might be dead lettered multiple times.
+        # The value must be between 5 and 100.
+        #
+        # The number of delivery attempts is defined as 1 + (the sum of number of NACKs and number of times the
+        # acknowledgement deadline has been exceeded for the message). A NACK is any call to ModifyAckDeadline with a 0
+        # deadline. Note that client libraries may automatically extend ack_deadlines.
+        #
+        # This field will be honored on a best effort basis. If this parameter is 0, a default value of 5 is used.
+        #
+        # The dead letter topic must also be set. See {#dead_letter_topic=} and {#dead_letter_topic}.
+        #
+        # @param [Integer] new_dead_letter_max_delivery_attempts A value between 5 and 100. If this parameter is 0, a
+        #   default value of 5 is used.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   sub.dead_letter_topic.name #=> "projects/my-project/topics/my-dead-letter-topic"
+        #
+        #   sub.dead_letter_max_delivery_attempts = 20
+        #
+        def dead_letter_max_delivery_attempts= new_dead_letter_max_delivery_attempts
+          ensure_grpc!
+          unless @grpc.dead_letter_policy&.dead_letter_topic
+            # Service error message "3:Invalid resource name given (name=)." does not identify param.
+            raise ArgumentError, "dead_letter_topic is required with dead_letter_max_delivery_attempts"
+          end
+          dead_letter_policy = @grpc.dead_letter_policy || Google::Cloud::PubSub::V1::DeadLetterPolicy.new
+          dead_letter_policy.max_delivery_attempts = new_dead_letter_max_delivery_attempts
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, dead_letter_policy: dead_letter_policy
+          @grpc = service.update_subscription update_grpc, :dead_letter_policy
+          @resource_name = nil
+        end
+
         ##
         # Whether message ordering has been enabled. When enabled, messages
         # published with the same `ordering_key` will be delivered in the order

data/lib/google/cloud/pubsub/topic.rb

@@ -285,6 +285,18 @@ module Google
         #   Managing Labels](https://cloud.google.com/pubsub/docs/labels).
         # @param [Boolean] message_ordering Whether to enable message ordering
         #   on the subscription.
+        # @param [Topic] dead_letter_topic The {Topic} to which dead letter messages for the subscription should be
+        #   published. Dead lettering is done on a best effort basis. The same message might be dead lettered multiple
+        #   times. The Cloud Pub/Sub service account associated with the enclosing subscription's parent project (i.e.,
+        #   `service-\\{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com`) must have permission to Publish() to
+        #   this topic.
+        #
+        #   The operation will fail if the topic does not exist. Users should ensure that there is a subscription
+        #   attached to this topic since messages published to a topic with no subscriptions are lost.
+        # @param [Integer] dead_letter_max_delivery_attempts The maximum number of delivery attempts for any message in
+        #   the subscription's dead letter policy. Dead lettering is done on a best effort basis. The same message might
+        #   be dead lettered multiple times. The value must be between 5 and 100. If this parameter is 0, a default
+        #   value of 5 is used. The `dead_letter_topic` must also be set.
         #
         # @return [Google::Cloud::PubSub::Subscription]
         #
@@ -307,11 +319,38 @@ module Google
         #                         deadline: 120,
         #                         endpoint: "https://example.com/push"
         #
+        # @example Configure a Dead Letter Queues policy:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   # Dead Letter Queue (DLQ) testing requires IAM bindings to the Cloud Pub/Sub service account that is
+        #   # automatically created and managed by the service team in a private project.
+        #   my_project_number = "000000000000"
+        #   service_account_email = "serviceAccount:service-#{my_project_number}@gcp-sa-pubsub.iam.gserviceaccount.com"
+        #
+        #   dead_letter_topic = pubsub.topic "my-dead-letter-topic"
+        #   dead_letter_subscription = dead_letter_topic.subscribe "my-dead-letter-sub"
+        #
+        #   dead_letter_topic.policy { |p| p.add "roles/pubsub.publisher", service_account_email }
+        #   dead_letter_subscription.policy { |p| p.add "roles/pubsub.subscriber", service_account_email }
+        #
+        #   topic = pubsub.topic "my-topic"
+        #   sub = topic.subscribe "my-topic-sub",
+        #                         dead_letter_topic: dead_letter_topic,
+        #                         dead_letter_max_delivery_attempts: 10
+        #
         def subscribe subscription_name, deadline: nil, retain_acked: false, retention: nil, endpoint: nil, labels: nil,
-                      message_ordering: nil
+                      message_ordering: nil, dead_letter_topic: nil, dead_letter_max_delivery_attempts: nil
           ensure_service!
           options = { deadline: deadline, retain_acked: retain_acked, retention: retention, endpoint: endpoint,
-                      labels: labels, message_ordering: message_ordering }
+                      labels: labels, message_ordering: message_ordering,
+                      dead_letter_max_delivery_attempts: dead_letter_max_delivery_attempts }
+          options[:dead_letter_topic_name] = dead_letter_topic.name if dead_letter_topic
+          if options[:dead_letter_max_delivery_attempts] && !options[:dead_letter_topic_name]
+            # Service error message "3:Invalid resource name given (name=)." does not identify param.
+            raise ArgumentError, "dead_letter_topic is required with dead_letter_max_delivery_attempts"
+          end
           grpc = service.create_subscription name, subscription_name, options
           Subscription.from_grpc grpc, service
         end

data/lib/google/cloud/pubsub/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module PubSub
-      VERSION = "1.2.2".freeze
+      VERSION = "1.3.0".freeze
     end
 
     Pubsub = PubSub unless const_defined? :Pubsub

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-pubsub
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-02-04 00:00:00.000000000 Z
+date: 2020-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby