google-cloud-pubsub 1.0.2 → 2.19.0

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

@@ -39,7 +39,7 @@ module Google
       #   subscriber.start
       #
       #   # Shut down the subscriber when ready to stop receiving messages.
-      #   subscriber.stop.wait!
+      #   subscriber.stop!
       #
       class ReceivedMessage
         ##
@@ -63,6 +63,44 @@ 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.
+        #
+        # @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
@@ -91,6 +129,28 @@ module Google
         end
         alias msg_id message_id
 
+        ##
+        # Identifies related messages for which publish order should be
+        # respected.
+        #
+        # Google Cloud Pub/Sub ordering keys provide the ability to ensure
+        # related messages are sent to subscribers in the order in which they
+        # were published. Messages can be tagged with an ordering key, a string
+        # that identifies related messages for which publish order should be
+        # respected. The service guarantees that, for a given ordering key and
+        # publisher, messages are sent to subscribers in the order in which they
+        # were published. Ordering does not require sacrificing high throughput
+        # or scalability, as the service automatically distributes messages for
+        # different ordering keys across subscribers.
+        #
+        # See {Topic#publish_async} and {Subscription#listen}.
+        #
+        # @return [String]
+        #
+        def ordering_key
+          message.ordering_key
+        end
+
         ##
         # The time at which the message was published.
         def published_at
@@ -101,6 +161,29 @@ module Google
         ##
         # Acknowledges receipt of the message.
         #
+        # @yield [callback] The block to be called when reject operation is done.
+        # @yieldparam [Google::Cloud::PubSub::AcknowledgeResult] Result object that contains the status and error.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   subscriber = sub.listen do |received_message|
+        #     puts received_message.message.data
+        #
+        #     received_message.acknowledge! do |result|
+        #       puts result.status
+        #     end
+        #   end
+        #
+        #   # Start background threads that will call block passed to listen.
+        #   subscriber.start
+        #
+        #   # Shut down the subscriber when ready to stop receiving messages.
+        #   subscriber.stop!
+        #
         # @example
         #   require "google/cloud/pubsub"
         #
@@ -117,11 +200,16 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
-        def acknowledge!
+        def acknowledge! &block
           ensure_subscription!
-          subscription.acknowledge ack_id
+          if subscription.respond_to?(:exactly_once_delivery_enabled) && subscription.exactly_once_delivery_enabled
+            subscription.acknowledge ack_id, &block
+          else
+            subscription.acknowledge ack_id
+            yield AcknowledgeResult.new(AcknowledgeResult::SUCCESS) if block_given?
+          end
         end
         alias ack! acknowledge!
 
@@ -137,6 +225,30 @@ module Google
         #   seconds after the call is made. Specifying `0` may immediately make
         #   the message available for another pull request.
         #
+        # @yield [callback] The block to be called when reject operation is done.
+        # @yieldparam [Google::Cloud::PubSub::AcknowledgeResult] Result object that contains the status and error.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   subscriber = sub.listen do |received_message|
+        #     puts received_message.message.data
+        #
+        #     # Delay for 2 minutes
+        #     received_message.modify_ack_deadline! 120 do |result|
+        #       puts result.status
+        #     end
+        #   end
+        #
+        #   # Start background threads that will call block passed to listen.
+        #   subscriber.start
+        #
+        #   # Shut down the subscriber when ready to stop receiving messages.
+        #   subscriber.stop!
+        #
         # @example
         #   require "google/cloud/pubsub"
         #
@@ -154,11 +266,16 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
-        def modify_ack_deadline! new_deadline
+        def modify_ack_deadline! new_deadline, &block
           ensure_subscription!
-          subscription.modify_ack_deadline new_deadline, ack_id
+          if subscription.respond_to?(:exactly_once_delivery_enabled) && subscription.exactly_once_delivery_enabled
+            subscription.modify_ack_deadline new_deadline, ack_id, &block
+          else
+            subscription.modify_ack_deadline new_deadline, ack_id
+            yield AcknowledgeResult.new(AcknowledgeResult::SUCCESS) if block_given?
+          end
         end
 
         ##
@@ -167,6 +284,30 @@ module Google
         #
         # This will make the message available for redelivery.
         #
+        # @yield [callback] The block to be called when reject operation is done.
+        # @yieldparam [Google::Cloud::PubSub::AcknowledgeResult] Result object that contains the status and error.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   subscriber = sub.listen do |received_message|
+        #     puts received_message.message.data
+        #
+        #     # Release message back to the API.
+        #     received_message.reject! do |result|
+        #       puts result.status
+        #     end
+        #   end
+        #
+        #   # Start background threads that will call block passed to listen.
+        #   subscriber.start
+        #
+        #   # Shut down the subscriber when ready to stop receiving messages.
+        #   subscriber.stop!
+        #
         # @example
         #   require "google/cloud/pubsub"
         #
@@ -184,14 +325,34 @@ module Google
         #   subscriber.start
         #
         #   # Shut down the subscriber when ready to stop receiving messages.
-        #   subscriber.stop.wait!
+        #   subscriber.stop!
         #
-        def reject!
-          modify_ack_deadline! 0
+        def reject! &block
+          modify_ack_deadline! 0, &block
         end
         alias nack! reject!
         alias ignore! reject!
 
+        # @private
+        def hash
+          @grpc.hash
+        end
+
+        # @private
+        def eql? other
+          return false unless other.is_a? self.class
+          @grpc.hash == other.hash
+        end
+        # @private
+        alias == eql?
+
+        # @private
+        def <=> other
+          return nil unless other.is_a? self.class
+          other_grpc = other.instance_variable_get :@grpc
+          @grpc <=> other_grpc
+        end
+
         ##
         # @private New ReceivedMessage from a
         # Google::Cloud::PubSub::V1::ReceivedMessage object.

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

@@ -0,0 +1,88 @@
+# 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.
+      #
+      # @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
+        attr_reader :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/schema/list.rb

@@ -0,0 +1,180 @@
+# Copyright 2021 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 "delegate"
+
+module Google
+  module Cloud
+    module PubSub
+      class Schema
+        ##
+        # Schema::List is a special case Array with additional values.
+        class List < DelegateClass(::Array)
+          ##
+          # If not empty, indicates that there are more schemas
+          # that match the request and this value should be passed to
+          # the next {Google::Cloud::PubSub::Project#schemas} to continue.
+          attr_accessor :token
+
+          ##
+          # @private Create a new Schema::List with an array of values.
+          def initialize arr = []
+            @prefix = nil
+            @token = nil
+            @view = nil
+            @max = nil
+            super arr
+          end
+
+          ##
+          # Whether there a next page of schemas.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::PubSub.new
+          #
+          #   schemas = pubsub.schemas
+          #   if schemas.next?
+          #     next_schemas = schemas.next
+          #   end
+          #
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieve the next page of schemas.
+          #
+          # @return [Schema::List]
+          #
+          # @example
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::PubSub.new
+          #
+          #   schemas = pubsub.schemas
+          #   if schemas.next?
+          #     next_schemas = schemas.next
+          #   end
+          #
+          def next
+            return nil unless next?
+            ensure_service!
+            next_schemas
+          end
+
+          ##
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
+          #
+          # An Enumerator is returned if no block is given.
+          #
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
+          #
+          # @param [Integer] request_limit The upper limit of API requests to
+          #   make to load all schemas. Default is no limit.
+          # @yield [schema] The block for accessing each schema.
+          # @yieldparam [Schema] schema The schema object.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each schema by passing a block:
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::PubSub.new
+          #
+          #   schemas = pubsub.schemas
+          #   schemas.all do |schema|
+          #     puts schema.name
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::PubSub.new
+          #
+          #   schemas = pubsub.schemas
+          #   all_names = schemas.all.map do |schema|
+          #     schema.name
+          #   end
+          #
+          # @example Limit the number of API calls made:
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::PubSub.new
+          #
+          #   schemas = pubsub.schemas
+          #   schemas.all(request_limit: 10) do |schema|
+          #     puts schema.name
+          #   end
+          #
+          def all request_limit: nil, &block
+            request_limit = request_limit.to_i if request_limit
+            return enum_for :all, request_limit: request_limit unless block_given?
+            results = self
+            loop do
+              results.each(&block)
+              if request_limit
+                request_limit -= 1
+                break if request_limit.negative?
+              end
+              break unless results.next?
+              results = results.next
+            end
+          end
+
+          ##
+          # @private New Schemas::List from a
+          # Google::Cloud::PubSub::V1::ListSchemasRequest object.
+          def self.from_grpc grpc_list, service, view, max = nil
+            subs = new(Array(grpc_list.schemas).map do |grpc|
+              Schema.from_grpc grpc, service
+            end)
+            token = grpc_list.next_page_token
+            token = nil if token == "".freeze
+            subs.instance_variable_set :@token,   token
+            subs.instance_variable_set :@service, service
+            subs.instance_variable_set :@view,    view
+            subs.instance_variable_set :@max,     max
+            subs
+          end
+
+          protected
+
+          ##
+          # @private Raise an error unless an active connection to the service
+          # is available.
+          def ensure_service!
+            raise "Must have active connection to service" unless @service
+          end
+
+          def next_schemas
+            options = { prefix: @prefix, token: @token, max: @max }
+            grpc = @service.list_schemas @view, options
+            self.class.from_grpc grpc, @service, @view, @max
+          end
+        end
+      end
+    end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
+  end
+end