google-cloud-pubsub 1.6.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65b27ec5d2bc4fe8948301c5a6d56adb62e436bb0d5da35997cc77bb05e2af59
-  data.tar.gz: 9f7eba965695f834c77cb50f229b2a84ae9d0039528f203b5a0e9db6758e0ae9
+  metadata.gz: 176ccfcca66573d1d858c76096cf3e2cbb437163aeaf0993df5e394594158a4d
+  data.tar.gz: 02c9e180e88ef9a5d87e68677fe40814b26a903fb65aa994ae50473080f2d27c
 SHA512:
-  metadata.gz: 4cb430ff1c904e6ca3248f024e8b9f82aafc5c28ca90fd45f5265a86df70fc7e48cf68d93e0b71ef4d1946beb2319e898aa6c3c8ca4f78085490b330899f9991
-  data.tar.gz: 8b0af8b3bb8eed0dc11c5e30a61bfb0502758340f5f7062c5f040b371231f58c057bc2d154cdb5a572e81bb674f12c27ed2f734f267a3006f06cd53b2ee6bee8
+  metadata.gz: 2a1b5a6de847eb054cf72ec388eca205cf5e3a03dc00b0125ef9a9a0eb2bcd94fb21389f3cef3b56983e59e9f2a11672d02f5a2b7005be7e2658a60633798896
+  data.tar.gz: 1c81891756ab4f80a54ed12663a9a339b0e1ba57f821e3ee7f5f0a545a60b6cec4b5c94828bc888bc5b51cf4ab947a642ce3895b8103bc4824ce3026fac56d49

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Release History
 
+### 1.7.0 / 2020-05-21
+
+#### Features
+
+* Add Retry Policy support
+  * Add RetryPolicy
+  * Add retry_policy param to Topic#subscribe
+  * Add Subscription#retry_policy
+  * Add Subscription#retry_policy=
+* Set client-scoped UUID in initial StreamingPullRequest#client_id
+
 ### 1.6.1 / 2020-05-06
 
 #### Documentation

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

@@ -0,0 +1,90 @@
+# Copyright 2016 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/errors"
+
+module Google
+  module Cloud
+    module PubSub
+      ##
+      # # RetryPolicy
+      #
+      # An immutable Retry Policy value object that specifies how Cloud Pub/Sub retries message delivery.
+      #
+      # Retry delay will be exponential based on provided minimum and maximum backoffs. (See [Exponential
+      # backoff](https://en.wikipedia.org/wiki/Exponential_backoff).)
+      #
+      # Retry Policy will be triggered on NACKs or acknowledgement deadline exceeded events for a given message.
+      #
+      # Retry Policy is implemented on a best effort basis. At times, the delay between consecutive deliveries may not
+      # match the configuration. That is, delay can be more or less than configured backoff.
+      #
+      # **EXPERIMENTAL:** 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.
+      #
+      # @attr [Numeric] minimum_backoff The minimum delay between consecutive deliveries of a given message. Value
+      #   should be between 0 and 600 seconds. The default value is 10 seconds.
+      # @attr [Numeric] maximum_backoff The maximum delay between consecutive deliveries of a given message. Value
+      #   should be between 0 and 600 seconds. The default value is 600 seconds.
+      #
+      # @example
+      #   require "google/cloud/pubsub"
+      #
+      #   pubsub = Google::Cloud::PubSub.new
+      #
+      #   sub = pubsub.subscription "my-topic-sub"
+      #
+      #   sub.retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
+      #
+      #   sub.retry_policy.minimum_backoff #=> 5
+      #   sub.retry_policy.maximum_backoff #=> 300
+      #
+      class RetryPolicy
+        attr_reader :minimum_backoff, :maximum_backoff
+
+        ##
+        # Creates a new, immutable RetryPolicy value object.
+        #
+        # @attr [Numeric, nil] minimum_backoff The minimum delay between consecutive deliveries of a given message.
+        #   Value should be between 0 and 600 seconds. If `nil` is provided, the default value is 10 seconds.
+        # @attr [Numeric, nil] maximum_backoff The maximum delay between consecutive deliveries of a given message.
+        #   Value should be between 0 and 600 seconds. If `nil` is provided, the default value is 600 seconds.
+        #
+        def initialize minimum_backoff: nil, maximum_backoff: nil
+          @minimum_backoff = minimum_backoff
+          @maximum_backoff = maximum_backoff
+        end
+
+        ##
+        # @private Convert the RetryPolicy to a Google::Cloud::PubSub::V1::RetryPolicy object.
+        def to_grpc
+          Google::Cloud::PubSub::V1::RetryPolicy.new(
+            minimum_backoff: Convert.number_to_duration(minimum_backoff),
+            maximum_backoff: Convert.number_to_duration(maximum_backoff)
+          )
+        end
+
+        ##
+        # @private New RetryPolicy from a Google::Cloud::PubSub::V1::RetryPolicy object.
+        def self.from_grpc grpc
+          new(
+            minimum_backoff: Convert.duration_to_number(grpc.minimum_backoff),
+            maximum_backoff: Convert.duration_to_number(grpc.maximum_backoff)
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -19,6 +19,7 @@ require "google/cloud/pubsub/convert"
 require "google/cloud/pubsub/version"
 require "google/cloud/pubsub/v1"
 require "google/gax/errors"
+require "securerandom"
 
 module Google
   module Cloud
@@ -28,6 +29,12 @@ module Google
       # methods.
       class Service
         attr_accessor :project, :credentials, :host, :timeout, :client_config
+        ###
+        # The same client_id is used across all streaming pull connections that are created by this client. This is
+        # intentional, as it indicates to the server that any guarantees, such as message ordering, made for a stream
+        # that is disconnected will be made for the stream that is created to replace it. The attr_accessor allows the
+        # value to be replaced for unit testing.
+        attr_accessor :client_id
 
         ##
         # Creates a new Service instance.
@@ -38,6 +45,7 @@ module Google
           @host = host || V1::PublisherClient::SERVICE_ADDRESS
           @timeout = timeout
           @client_config = client_config || {}
+          @client_id = SecureRandom.uuid.freeze
         end
 
         def channel
@@ -248,6 +256,7 @@ module Google
               labels:                     labels,
               enable_message_ordering:    message_ordering,
               dead_letter_policy:         dead_letter_policy(options),
+              retry_policy:               options[:retry_policy],
               options:                    default_options
           end
         end

data/lib/google/cloud/pubsub/subscriber/stream.rb

@@ -363,6 +363,7 @@ module Google
               req.stream_ack_deadline_seconds = @subscriber.deadline
               req.modify_deadline_ack_ids += @inventory.ack_ids
               req.modify_deadline_seconds += @inventory.ack_ids.map { @subscriber.deadline }
+              req.client_id = @subscriber.service.client_id
             end
           end
 

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

@@ -18,6 +18,7 @@ require "google/cloud/errors"
 require "google/cloud/pubsub/subscription/list"
 require "google/cloud/pubsub/subscription/push_config"
 require "google/cloud/pubsub/received_message"
+require "google/cloud/pubsub/retry_policy"
 require "google/cloud/pubsub/snapshot"
 require "google/cloud/pubsub/subscriber"
 require "google/cloud/pubsub/v1"
@@ -483,6 +484,65 @@ module Google
           @resource_name = nil
         end
 
+        ##
+        # A policy that specifies how Cloud Pub/Sub retries message delivery for this subscription. If `nil`, the
+        # default retry policy is applied. This generally implies that messages will be retried as soon as possible
+        # for healthy subscribers. Retry Policy will be triggered on NACKs or acknowledgement deadline exceeded events
+        # for a given message.
+        #
+        # **EXPERIMENTAL:** 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 [RetryPolicy, nil] The retry policy for the subscription, or `nil`.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #
+        #   sub.retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
+        #
+        #   sub.retry_policy.minimum_backoff #=> 5
+        #   sub.retry_policy.maximum_backoff #=> 300
+        #
+        def retry_policy
+          ensure_grpc!
+          return nil unless @grpc.retry_policy
+          RetryPolicy.from_grpc @grpc.retry_policy
+        end
+
+        ##
+        # Sets a policy that specifies how Cloud Pub/Sub retries message delivery for this subscription. If `nil`, the
+        # default retry policy is applied. This generally implies that messages will be retried as soon as possible
+        # for healthy subscribers. Retry Policy will be triggered on NACKs or acknowledgement deadline exceeded events
+        # for a given message.
+        #
+        # **EXPERIMENTAL:** 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.
+        #
+        # @param [RetryPolicy, nil] new_retry_policy A new retry policy for the subscription, or `nil`.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #
+        #   sub.retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
+        #
+        #   sub.retry_policy.minimum_backoff #=> 5
+        #   sub.retry_policy.maximum_backoff #=> 300
+        #
+        def retry_policy= new_retry_policy
+          ensure_grpc!
+          new_retry_policy = new_retry_policy.to_grpc if new_retry_policy
+          update_grpc = Google::Cloud::PubSub::V1::Subscription.new name: name, retry_policy: new_retry_policy
+          @grpc = service.update_subscription update_grpc, :retry_policy
+        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

@@ -19,6 +19,7 @@ require "google/cloud/pubsub/async_publisher"
 require "google/cloud/pubsub/batch_publisher"
 require "google/cloud/pubsub/subscription"
 require "google/cloud/pubsub/policy"
+require "google/cloud/pubsub/retry_policy"
 
 module Google
   module Cloud
@@ -297,6 +298,13 @@ module Google
         #   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.
+        # @param [RetryPolicy] retry_policy A policy that specifies how Cloud Pub/Sub retries message delivery for
+        #   this subscription. If not set, the default retry policy is applied. This generally implies that messages
+        #   will be retried as soon as possible for healthy subscribers. Retry Policy will be triggered on NACKs or
+        #   acknowledgement deadline exceeded events for a given message.
+        #
+        #   **EXPERIMENTAL:** 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 [Google::Cloud::PubSub::Subscription]
         #
@@ -340,8 +348,19 @@ module Google
         #                         dead_letter_topic: dead_letter_topic,
         #                         dead_letter_max_delivery_attempts: 10
         #
+        # @example Configure a Retry Policy:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   retry_policy = Google::Cloud::PubSub::RetryPolicy.new minimum_backoff: 5, maximum_backoff: 300
+        #   sub = topic.subscribe "my-topic-sub", retry_policy: retry_policy
+        #
         def subscribe subscription_name, deadline: nil, retain_acked: false, retention: nil, endpoint: nil, labels: nil,
-                      message_ordering: nil, dead_letter_topic: nil, dead_letter_max_delivery_attempts: nil
+                      message_ordering: nil, dead_letter_topic: nil, dead_letter_max_delivery_attempts: nil,
+                      retry_policy: nil
           ensure_service!
           options = { deadline: deadline, retain_acked: retain_acked, retention: retention, endpoint: endpoint,
                       labels: labels, message_ordering: message_ordering,
@@ -351,6 +370,7 @@ module Google
             # 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
+          options[:retry_policy] = retry_policy.to_grpc if retry_policy
           grpc = service.create_subscription name, subscription_name, options
           Subscription.from_grpc grpc, service
         end

data/lib/google/cloud/pubsub/v1/doc/google/pubsub/v1/pubsub.rb

@@ -455,8 +455,11 @@ module Google
       #     The message.
       # @!attribute [rw] delivery_attempt
       #   @return [Integer]
-      #     Delivery attempt counter is 1 + (the sum of number of NACKs and number of
-      #     ack_deadline exceeds) for this message.
+      #     The approximate number of times that Cloud Pub/Sub has attempted to deliver
+      #     the associated message to a subscriber.
+      #
+      #     More precisely, this is 1 + (number of NACKs) +
+      #     (number of ack_deadline exceeds) for this 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
@@ -464,13 +467,10 @@ module Google
       #     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.
+      #     Upon the first delivery of a given message, `delivery_attempt` will have a
+      #     value of 1. The value is calculated at best effort and is approximate.
       #
       #     If a DeadLetterPolicy is not set on the subscription, this will be 0.
-      #     <b>EXPERIMENTAL:</b> This feature is part of a closed alpha release. 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.
       class ReceivedMessage; end
 
       # Request for the GetSubscription method.

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module PubSub
-      VERSION = "1.6.1".freeze
+      VERSION = "1.7.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.6.1
+  version: 1.7.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-06 00:00:00.000000000 Z
+date: 2020-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -278,6 +278,7 @@ files:
 - lib/google/cloud/pubsub/project.rb
 - lib/google/cloud/pubsub/publish_result.rb
 - lib/google/cloud/pubsub/received_message.rb
+- lib/google/cloud/pubsub/retry_policy.rb
 - lib/google/cloud/pubsub/service.rb
 - lib/google/cloud/pubsub/snapshot.rb
 - lib/google/cloud/pubsub/snapshot/list.rb