google-cloud-pubsub 0.26.0 → 0.27.0

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

@@ -0,0 +1,96 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# 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
+#
+#     http://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.
+
+
+module Google
+  module Cloud
+    module Pubsub
+      ##
+      # # PublishResult
+      #
+      class PublishResult
+        ##
+        # @private Create an PublishResult object.
+        def initialize message, error = nil
+          @message = message
+          @error = error
+        end
+
+        ##
+        # The message.
+        def message
+          @message
+        end
+        alias_method :msg, :message
+
+        ##
+        # The message's data.
+        def data
+          message.data
+        end
+
+        ##
+        # The message's attributes.
+        def attributes
+          message.attributes
+        end
+
+        ##
+        # The ID of the message, assigned by the server at publication
+        # time. Guaranteed to be unique within the topic.
+        def message_id
+          message.message_id
+        end
+        alias_method :msg_id, :message_id
+
+        ##
+        # The time at which the message was published.
+        def published_at
+          message.published_at
+        end
+        alias_method :publish_time, :published_at
+
+        ##
+        # The error that was raised when published, if any.
+        def error
+          @error
+        end
+
+        ##
+        # Whether the publish request was successful.
+        def succeeded?
+          error.nil?
+        end
+
+        # Whether the publish request failed.
+        def failed?
+          !succeeded?
+        end
+
+        ##
+        # @private Create an PublishResult object from a message protobuf.
+        def self.from_grpc msg_grpc
+          new Message.from_grpc(msg_grpc)
+        end
+
+        ##
+        # @private Create an PublishResult object from a message protobuf and an
+        # error.
+        def self.from_error msg_grpc, error
+          new Message.from_grpc(msg_grpc), error
+        end
+      end
+    end
+  end
+end

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

@@ -66,13 +66,14 @@ module Google
         alias_method :msg, :message
 
         ##
-        # The received message's data.
+        # The received message payload. This data is a list of bytes encoded as
+        # ASCII-8BIT.
         def data
           message.data
         end
 
         ##
-        # The received message's attributes.
+        # Optional attributes for the received message.
         def attributes
           message.attributes
         end
@@ -85,6 +86,13 @@ module Google
         end
         alias_method :msg_id, :message_id
 
+        ##
+        # The time at which the message was published.
+        def published_at
+          message.published_at
+        end
+        alias_method :publish_time, :published_at
+
         ##
         # Acknowledges receipt of the message.
         #
@@ -135,6 +143,32 @@ module Google
           ensure_subscription!
           subscription.delay new_deadline, ack_id
         end
+        alias_method :modify_ack_deadline!, :delay!
+
+        ##
+        # Resets the acknowledge deadline for the message without acknowledging
+        # it.
+        #
+        # This will make the message available for redelivery.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::Pubsub.new
+        #
+        #   sub = pubsub.subscription "my-topic-sub"
+        #   received_message = sub.pull.first
+        #   if received_message
+        #     puts received_message.message.data
+        #     # Release message back to the API.
+        #     received_message.reject!
+        #   end
+        #
+        def reject!
+          delay! 0
+        end
+        alias_method :nack!, :reject!
+        alias_method :ignore!, :reject!
 
         ##
         # @private New ReceivedMessage from a

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

@@ -15,6 +15,7 @@
 
 require "google/cloud/errors"
 require "google/cloud/pubsub/credentials"
+require "google/cloud/pubsub/convert"
 require "google/cloud/pubsub/version"
 require "google/cloud/pubsub/v1"
 require "google/gax/errors"
@@ -145,11 +146,6 @@ module Google
         # The messages parameter is an array of arrays.
         # The first element is the data, second is attributes hash.
         def publish topic, messages
-          messages = messages.map do |data, attributes|
-            Google::Pubsub::V1::PubsubMessage.new(
-              data: data, attributes: attributes)
-          end
-
           execute do
             publisher.publish topic_path(topic), messages,
                               options: default_options
@@ -214,7 +210,7 @@ module Google
                         end
           deadline = options[:deadline]
           retain_acked = options[:retain_acked]
-          mrd = number_to_duration options[:retention]
+          mrd = Convert.number_to_duration options[:retention]
 
           execute do
             subscriber.create_subscription name,
@@ -227,6 +223,14 @@ module Google
           end
         end
 
+        def update_subscription subscription_obj, *fields
+          mask = Google::Protobuf::FieldMask.new paths: fields.map(&:to_s)
+          execute do
+            subscriber.update_subscription \
+              subscription_obj, mask, options: default_options
+          end
+        end
+
         ##
         # Deletes an existing subscription.
         # All pending messages in the subscription are immediately dropped.
@@ -252,6 +256,12 @@ module Google
           end
         end
 
+        def streaming_pull request_enum
+          execute do
+            subscriber.streaming_pull request_enum, options: default_options
+          end
+        end
+
         ##
         # Acknowledges receipt of a message.
         def acknowledge subscription, *ack_ids
@@ -332,7 +342,8 @@ module Google
         def seek subscription, time_or_snapshot
           subscription = subscription_path(subscription)
           execute do
-            if (time = time_to_timestamp time_or_snapshot)
+            if a_time? time_or_snapshot
+              time = Convert.time_to_timestamp time_or_snapshot
               subscriber.seek subscription, time: time, options: default_options
             else
               if time_or_snapshot.is_a? Snapshot
@@ -425,6 +436,13 @@ module Google
 
         protected
 
+        def a_time? obj
+          return false unless obj.respond_to? :to_time
+          # Rails' String#to_time returns nil if the string doesn't parse.
+          return false if obj.to_time.nil?
+          true
+        end
+
         def default_headers
           { "google-cloud-resource-prefix" => "projects/#{@project}" }
         end
@@ -433,27 +451,6 @@ module Google
           Google::Gax::CallOptions.new kwargs: default_headers
         end
 
-        ##
-        # @private Get a Google::Protobuf::Timestamp object from a Time object.
-        def time_to_timestamp time
-          return nil if time.nil?
-          # Make sure to_time is supported.
-          return nil unless time.respond_to? :to_time
-          time = time.to_time
-          # Make sure we have a Time object.
-          # Rails' String#to_time returns nil if the string doesn't parse.
-          return nil unless time
-          Google::Protobuf::Timestamp.new seconds: time.to_i, nanos: time.nsec
-        end
-
-        def number_to_duration number
-          return nil if number.nil?
-
-          Google::Protobuf::Duration.new \
-            seconds: number.to_i,
-            nanos: (number.remainder(1) * 1000000000).round
-        end
-
         def execute
           yield
         rescue Google::Gax::GaxError => e

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

@@ -0,0 +1,185 @@
+# Copyright 2017 Google Inc. All rights reserved.
+#
+# 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
+#
+#     http://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/pubsub/service"
+require "google/cloud/pubsub/subscriber/stream"
+require "monitor"
+
+module Google
+  module Cloud
+    module Pubsub
+      ##
+      # Subscriber object used to stream and process messages from a
+      # Subscription. See {Google::Cloud::Pubsub::Subscription#listen}
+      #
+      # @example
+      #   require "google/cloud/pubsub"
+      #
+      #   pubsub = Google::Cloud::Pubsub.new
+      #
+      #   sub = pubsub.subscription "my-topic-sub"
+      #
+      #   subscriber = sub.listen do |msg|
+      #     # process msg
+      #     msg.ack!
+      #   end
+      #
+      #   subscriber.start
+      #
+      #   # Shut down the subscriber when ready to stop receiving messages.
+      #   subscriber.stop.wait!
+      #
+      # @attr_reader [String] subscription_name The name of the subscription the
+      #   messages are pulled from.
+      # @attr_reader [Proc] callback The procedure that will handle the messages
+      #   received from the subscription.
+      # @attr_reader [Numeric] deadline The default number of seconds the stream
+      #   will hold received messages before modifying the message's ack
+      #   deadline. The minimum is 10, the maximum is 600. Default is 60.
+      # @attr_reader [Integer] streams The number of concurrent streams to open
+      #   to pull messages from the subscription. Default is 4.
+      # @attr_reader [Integer] inventory The number of received messages to be
+      #   collected by subscriber. Default is 1,000.
+      # @attr_reader [Integer] callback_threads The number of threads used to
+      #   handle the received messages. Default is 8.
+      # @attr_reader [Integer] push_threads The number of threads to handle
+      #   acknowledgement ({ReceivedMessage#ack!}) and delay messages
+      #   ({ReceivedMessage#nack!}, {ReceivedMessage#delay!}). Default is 4.
+      #
+      class Subscriber
+        include MonitorMixin
+
+        attr_reader :subscription_name, :callback, :deadline, :streams,
+                    :inventory, :callback_threads, :push_threads
+
+        ##
+        # @private Implementation attributes.
+        attr_reader :stream_inventory, :stream_pool, :thread_pool, :service
+
+        ##
+        # @private Create an empty {Subscriber} object.
+        def initialize subscription_name, callback, deadline: nil, streams: nil,
+                       inventory: nil, threads: {}, service: nil
+          @callback = callback
+          @subscription_name = subscription_name
+          @deadline = deadline || 60
+          @streams = streams || 4
+          @inventory = inventory || 1000
+          @callback_threads = (threads[:callback] || 8).to_i
+          @push_threads = (threads[:push] || 4).to_i
+
+          @stream_inventory = @inventory.fdiv(@streams).ceil
+          @service = service
+
+          @started = nil
+          @stopped = nil
+
+          stream_pool = @streams.times.map do
+            Thread.new { Stream.new self }
+          end
+          @stream_pool = stream_pool.map(&:value)
+
+          super() # to init MonitorMixin
+        end
+
+        ##
+        # Starts the subscriber pulling from the subscription and processing the
+        # received messages.
+        #
+        # @return [Subscriber] returns self so calls can be chained.
+        def start
+          start_pool = synchronize do
+            @started = true
+            @stopped = false
+
+            @stream_pool.map do |stream|
+              Thread.new { stream.start }
+            end
+          end
+          start_pool.join
+
+          self
+        end
+
+        ##
+        # Begins the process of stopping the subscriber. Unhandled received
+        # messages will be processed, but no new messages will be pulled from
+        # the subscription. Use {#wait!} to block until the subscriber is fully
+        # stopped and all received messages have been processed.
+        #
+        # @return [Subscriber] returns self so calls can be chained.
+        def stop
+          stop_pool = synchronize do
+            @started = false
+            @stopped = true
+
+            @stream_pool.map do |stream|
+              Thread.new { stream.stop }
+            end
+          end
+          stop_pool.join
+
+          self
+        end
+
+        ##
+        # Blocks until the subscriber is fully stopped and all received messages
+        # have been handled. Does not stop the subscriber. To stop the
+        # subscriber, first call {#stop} and then call {#wait!} to block until
+        # the subscriber is stopped.
+        #
+        # @return [Subscriber] returns self so calls can be chained.
+        def wait!
+          wait_pool = synchronize do
+            @stream_pool.map do |stream|
+              Thread.new { stream.wait! }
+            end
+          end
+          wait_pool.join
+
+          self
+        end
+
+        ##
+        # Whether the subscriber has been started.
+        #
+        # @return [boolean] `true` when started, `false` otherwise.
+        def started?
+          synchronize { @started }
+        end
+
+        ##
+        # Whether the subscriber has been stopped.
+        #
+        # @return [boolean] `true` when stopped, `false` otherwise.
+        def stopped?
+          synchronize { @stopped }
+        end
+
+        ##
+        # @private
+        def to_s
+          format "(subscription: %s, streams: %i)", subscription_name, streams
+        end
+
+        ##
+        # @private
+        def inspect
+          "#<#{self.class.name} #{self}>"
+        end
+      end
+    end
+  end
+end