google-cloud-pubsub 0.20.0 → 2.6.1

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

@@ -0,0 +1,100 @@
+# Copyright 2015 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/pubsub/convert"
+
+module Google
+  module Cloud
+    module PubSub
+      ##
+      # Topic Batch Publisher object used to publish multiple messages at
+      # once.
+      #
+      # @example
+      #   require "google/cloud/pubsub"
+      #
+      #   pubsub = Google::Cloud::PubSub.new
+      #
+      #   topic = pubsub.topic "my-topic"
+      #   msgs = topic.publish do |batch_publisher|
+      #     batch_publisher.publish "task 1 completed", foo: :bar
+      #     batch_publisher.publish "task 2 completed", foo: :baz
+      #     batch_publisher.publish "task 3 completed", foo: :bif
+      #   end
+      #
+      class BatchPublisher
+        ##
+        # @private The messages to publish
+        attr_reader :messages
+
+        ##
+        # @private Create a new instance of the object.
+        def initialize data, attributes, ordering_key, extra_attrs
+          @messages = []
+          @mode = :batch
+          return if data.nil?
+          @mode = :single
+          publish data, attributes, ordering_key: ordering_key, **extra_attrs
+        end
+
+        ##
+        # Add a message to the batch to be published to the topic.
+        # All messages added to the batch will be published at once.
+        # See {Google::Cloud::PubSub::Topic#publish}
+        #
+        # @param [String, File] data The message payload. This will be converted
+        #   to bytes encoded as ASCII-8BIT.
+        # @param [Hash] attributes Optional attributes for the message.
+        # @param [String] ordering_key Identifies related messages for which
+        #   publish order should be respected.
+        #
+        # @example Multiple messages can be sent at the same time using a block:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   topic = pubsub.topic "my-topic"
+        #   msgs = topic.publish do |batch_publisher|
+        #     batch_publisher.publish "task 1 completed", foo: :bar
+        #     batch_publisher.publish "task 2 completed", foo: :baz
+        #     batch_publisher.publish "task 3 completed", foo: :bif
+        #   end
+        #
+        def publish data, attributes = nil, ordering_key: nil, **extra_attrs
+          msg = Convert.pubsub_message data, attributes, ordering_key, extra_attrs
+          @messages << msg
+        end
+
+        ##
+        # @private Create Message objects with message ids.
+        def to_gcloud_messages message_ids
+          msgs = @messages.zip(Array(message_ids)).map do |msg, id|
+            msg.message_id = id
+            Message.from_grpc msg
+          end
+          # Return just one Message if a single publish,
+          # otherwise return the array of Messages.
+          if @mode == :single && msgs.count <= 1
+            msgs.first
+          else
+            msgs
+          end
+        end
+      end
+    end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
+  end
+end

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

@@ -0,0 +1,91 @@
+# Copyright 2017 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 "time"
+
+module Google
+  module Cloud
+    module PubSub
+      ##
+      # @private Helper module for converting Pub/Sub values.
+      module Convert
+        module ClassMethods
+          def time_to_timestamp time
+            return nil if time.nil?
+
+            # Force the object to be a Time object.
+            time = time.to_time
+
+            Google::Protobuf::Timestamp.new seconds: time.to_i, nanos: time.nsec
+          end
+
+          def timestamp_to_time timestamp
+            return nil if timestamp.nil?
+
+            Time.at timestamp.seconds, Rational(timestamp.nanos, 1000)
+          end
+
+          def number_to_duration number
+            return nil if number.nil?
+
+            Google::Protobuf::Duration.new seconds: number.to_i, nanos: (number.remainder(1) * 1_000_000_000).round
+          end
+
+          def duration_to_number duration
+            return nil if duration.nil?
+
+            return duration.seconds if duration.nanos.zero?
+
+            duration.seconds + (duration.nanos / 1_000_000_000.0)
+          end
+
+          def pubsub_message data, attributes, ordering_key, extra_attrs
+            # TODO: allow data to be a Message object,
+            # then ensure attributes and ordering_key are nil
+            if data.is_a?(::Hash) && (attributes.nil? || attributes.empty?)
+              attributes = data.merge extra_attrs
+              data = nil
+            else
+              attributes = Hash(attributes).merge extra_attrs
+            end
+            # Convert IO-ish objects to strings
+            if data.respond_to?(:read) && data.respond_to?(:rewind)
+              data.rewind
+              data = data.read
+            end
+            # Convert data to encoded byte array to match the protobuf defn
+            data_bytes = String(data).dup.force_encoding(Encoding::ASCII_8BIT).freeze
+
+            # Convert attributes to strings to match the protobuf definition
+            attributes = Hash[attributes.map { |k, v| [String(k), String(v)] }]
+
+            # Ordering Key must always be a string
+            ordering_key = String(ordering_key).freeze
+
+            Google::Cloud::PubSub::V1::PubsubMessage.new(
+              data:         data_bytes,
+              attributes:   attributes,
+              ordering_key: ordering_key
+            )
+          end
+        end
+
+        extend ClassMethods
+      end
+    end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
+  end
+end

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

@@ -1,10 +1,10 @@
-# Copyright 2015 Google Inc. All rights reserved.
+# Copyright 2015 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
 #
-#     http://www.apache.org/licenses/LICENSE-2.0
+#     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,
@@ -13,19 +13,35 @@
 # limitations under the License.
 
 
-require "google/cloud/credentials"
+require "googleauth"
+require "google/cloud/pubsub/v1/publisher/credentials"
 
 module Google
   module Cloud
-    module Pubsub
+    module PubSub
       ##
-      # @private Represents the OAuth 2.0 signing logic for Pub/Sub.
-      class Credentials < Google::Cloud::Credentials
-        SCOPE = ["https://www.googleapis.com/auth/pubsub"]
-        PATH_ENV_VARS = %w(PUBSUB_KEYFILE GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
-        JSON_ENV_VARS = %w(PUBSUB_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON
-                           GCLOUD_KEYFILE_JSON)
+      # # Credentials
+      #
+      # Represents the authentication and authorization used to connect to the
+      # Pub/Sub API.
+      #
+      # @example
+      #   require "google/cloud/pubsub"
+      #
+      #   keyfile = "/path/to/keyfile.json"
+      #   creds = Google::Cloud::PubSub::Credentials.new keyfile
+      #
+      #   pubsub = Google::Cloud::PubSub.new(
+      #     project_id: "my-project",
+      #     credentials: creds
+      #   )
+      #
+      #   pubsub.project_id #=> "my-project"
+      #
+      class Credentials < Google::Cloud::PubSub::V1::Publisher::Credentials
       end
     end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
   end
 end

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

@@ -0,0 +1,85 @@
+# Copyright 2019 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
+      ##
+      # Indicates that the {AsyncPublisher} has been stopped and cannot accept
+      # messages to publish.
+      #
+      class AsyncPublisherStopped < Google::Cloud::Error
+        def initialize message = "Can't publish when stopped."
+          super message
+        end
+      end
+
+      ##
+      # Indicates that the {AsyncPublisher} has not been enabled to publish
+      # messages with an ordering key. Use
+      # {AsyncPublisher#enable_message_ordering!} to enable publishing ordered
+      # messages.
+      #
+      class OrderedMessagesDisabled < Google::Cloud::Error
+        def initialize message = "Ordered messages are disabled."
+          super message
+        end
+      end
+
+      ##
+      # Indicates that the {Subscriber} for a {Subscription} with message
+      # ordering enabled has observed that a message has been delivered out of
+      # order.
+      #
+      class OrderedMessageDeliveryError < Google::Cloud::Error
+        attr_reader :ordered_message
+
+        def initialize ordered_message
+          @ordered_message = ordered_message
+
+          super "Ordered message delivered out of order."
+        end
+      end
+
+      ##
+      # Indicates that messages using the {#ordering_key} are not being
+      # published due to error. Future calls to {Topic#publish_async} with the
+      # {#ordering_key} will fail with this error.
+      #
+      # To allow future messages with the {#ordering_key} to be published, the
+      # {#ordering_key} must be passed to {Topic#resume_publish}.
+      #
+      # If this error is retrieved from {PublishResult#error}, inspect `cause`
+      # for the error raised while publishing.
+      #
+      # @!attribute [r] ordering_key
+      #   @return [String] The ordering key that is in a failed state.
+      #
+      class OrderingKeyError < Google::Cloud::Error
+        attr_reader :ordering_key
+
+        def initialize ordering_key
+          @ordering_key = ordering_key
+
+          super "Can't publish message using #{ordering_key}."
+        end
+      end
+    end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
+  end
+end

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

@@ -1,10 +1,10 @@
-# Copyright 2015 Google Inc. All rights reserved.
+# Copyright 2015 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
 #
-#     http://www.apache.org/licenses/LICENSE-2.0
+#     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,
@@ -13,11 +13,12 @@
 # limitations under the License.
 
 
+require "google/cloud/pubsub/convert"
 require "google/cloud/errors"
 
 module Google
   module Cloud
-    module Pubsub
+    module PubSub
       ##
       # # Message
       #
@@ -29,24 +30,31 @@ module Google
       # delayed.
       #
       # @example
-      #   require "google/cloud"
+      #   require "google/cloud/pubsub"
       #
-      #   gcloud = Google::Cloud.new
-      #   pubsub = gcloud.pubsub
+      #   pubsub = Google::Cloud::PubSub.new
       #
       #   # Publish a message
       #   topic = pubsub.topic "my-topic"
-      #   message = topic.publish "new-message"
-      #   puts message.data #=>  "new-message"
+      #   message = topic.publish "task completed"
+      #   message.data #=> "task completed"
       #
-      #   # Pull a message
+      #   # Listen for messages
       #   sub = pubsub.subscription "my-topic-sub"
-      #   received_message = sub.pull.first
-      #   puts received_message.message.data #=>  "new-message"
+      #   subscriber = sub.listen do |received_message|
+      #     # process message
+      #     received_message.acknowledge!
+      #   end
+      #
+      #   # Start background threads that will call the block passed to listen.
+      #   subscriber.start
+      #
+      #   # Shut down the subscriber when ready to stop receiving messages.
+      #   subscriber.stop!
       #
       class Message
         ##
-        # @private The gRPC Google::Pubsub::V1::PubsubMessage object.
+        # @private The gRPC Google::Cloud::PubSub::V1::PubsubMessage object.
         attr_accessor :grpc
 
         ##
@@ -56,19 +64,21 @@ module Google
           # Convert attributes to strings to match the protobuf definition
           attributes = Hash[attributes.map { |k, v| [String(k), String(v)] }]
 
-          @grpc = Google::Pubsub::V1::PubsubMessage.new(
-            data: String(data).encode("ASCII-8BIT"),
-            attributes: attributes)
+          @grpc = Google::Cloud::PubSub::V1::PubsubMessage.new(
+            data:       String(data).dup.force_encoding(Encoding::ASCII_8BIT),
+            attributes: attributes
+          )
         end
 
         ##
-        # The received data.
+        # The message payload. This data is a list of bytes encoded as
+        # ASCII-8BIT.
         def data
           @grpc.data
         end
 
         ##
-        # The received attributes.
+        # Optional attributes for the message.
         def attributes
           return @grpc.attributes.to_h if @grpc.attributes.respond_to? :to_h
           # Enumerable doesn't have to_h on Ruby 2.0, so fallback to this
@@ -81,16 +91,68 @@ module Google
         def message_id
           @grpc.message_id
         end
-        alias_method :msg_id, :message_id
+        alias msg_id message_id
+
+        ##
+        # The time at which the message was published.
+        def published_at
+          Convert.timestamp_to_time @grpc.publish_time
+        end
+        alias publish_time published_at
 
         ##
-        # @private New Message from a Google::Pubsub::V1::PubsubMessage object.
+        # 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
+          @grpc.ordering_key
+        end
+
+        # @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 Message from a Google::Cloud::PubSub::V1::PubsubMessage
+        # object.
         def self.from_grpc grpc
           new.tap do |m|
-            m.instance_variable_set "@grpc", grpc
+            m.instance_variable_set :@grpc, grpc
           end
         end
       end
     end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
   end
 end