google-cloud-pubsub 1.9.0

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

@@ -0,0 +1,47 @@
+# 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 "googleauth"
+require "google/cloud/pubsub/v1/credentials.rb"
+
+module Google
+  module Cloud
+    module PubSub
+      ##
+      # # 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::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

@@ -0,0 +1,158 @@
+# 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"
+require "google/cloud/errors"
+
+module Google
+  module Cloud
+    module PubSub
+      ##
+      # # Message
+      #
+      # Represents a Pub/Sub Message.
+      #
+      # Message objects are created by {Topic#publish}. {Subscription#pull}
+      # returns an array of {ReceivedMessage} objects, each of which contains a
+      # Message object. Each {ReceivedMessage} object can be acknowledged and/or
+      # delayed.
+      #
+      # @example
+      #   require "google/cloud/pubsub"
+      #
+      #   pubsub = Google::Cloud::PubSub.new
+      #
+      #   # Publish a message
+      #   topic = pubsub.topic "my-topic"
+      #   message = topic.publish "task completed"
+      #   message.data #=> "task completed"
+      #
+      #   # Listen for messages
+      #   sub = pubsub.subscription "my-topic-sub"
+      #   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.wait!
+      #
+      class Message
+        ##
+        # @private The gRPC Google::Cloud::PubSub::V1::PubsubMessage object.
+        attr_accessor :grpc
+
+        ##
+        # Create an empty Message object.
+        # This can be used to publish several messages in bulk.
+        def initialize data = nil, attributes = {}
+          # Convert attributes to strings to match the protobuf definition
+          attributes = Hash[attributes.map { |k, v| [String(k), String(v)] }]
+
+          @grpc = Google::Cloud::PubSub::V1::PubsubMessage.new(
+            data:       String(data).dup.force_encoding(Encoding::ASCII_8BIT),
+            attributes: attributes
+          )
+        end
+
+        ##
+        # The message payload. This data is a list of bytes encoded as
+        # ASCII-8BIT.
+        def data
+          @grpc.data
+        end
+
+        ##
+        # 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
+          Hash[@grpc.attributes.to_a]
+        end
+
+        ##
+        # The ID of this message, assigned by the server at publication time.
+        # Guaranteed to be unique within the topic.
+        def message_id
+          @grpc.message_id
+        end
+        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
+
+        ##
+        # 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
+          end
+        end
+      end
+    end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
+  end
+end

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

@@ -0,0 +1,187 @@
+# 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
+      ##
+      # # Policy
+      #
+      # Represents a Cloud IAM Policy for the Pub/Sub service.
+      #
+      # A common pattern for updating a resource's metadata, such as its Policy,
+      # is to read the current data from the service, update the data locally,
+      # and then send the modified data for writing. This pattern may result in
+      # a conflict if two or more processes attempt the sequence simultaneously.
+      # IAM solves this problem with the {Google::Cloud::PubSub::Policy#etag}
+      # property, which is used to verify whether the policy has changed since
+      # the last request. When you make a request to with an `etag` value, Cloud
+      # IAM compares the `etag` value in the request with the existing `etag`
+      # value associated with the policy. It writes the policy only if the
+      # `etag` values match.
+      #
+      # When you update a policy, first read the policy (and its current `etag`)
+      # from the service, then modify the policy locally, and then write the
+      # modified policy to the service. See
+      # {Google::Cloud::PubSub::Topic#policy} and
+      # {Google::Cloud::PubSub::Topic#policy=}.
+      #
+      # @see https://cloud.google.com/iam/docs/managing-policies Managing
+      #   policies
+      # @see https://cloud.google.com/pubsub/docs/reference/rpc/google.iam.v1#iampolicy
+      #   google.iam.v1.IAMPolicy
+      #
+      # @attr [String] etag Used to verify whether the policy has changed since
+      #   the last request. The policy will be written only if the `etag` values
+      #   match.
+      # @attr [Hash{String => Array<String>}] roles The bindings that associate
+      #   roles with an array of members. See [Understanding
+      #   Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+      #   listing of primitive and curated roles.
+      #   See [Binding](https://cloud.google.com/pubsub/docs/reference/rpc/google.iam.v1#binding)
+      #   for a listing of values and patterns for members.
+      #
+      # @example
+      #   require "google/cloud/pubsub"
+      #
+      #   pubsub = Google::Cloud::PubSub.new
+      #   topic = pubsub.topic "my-topic"
+      #
+      #   topic.policy do |p|
+      #     p.remove "roles/owner", "user:owner@example.com"
+      #     p.add "roles/owner", "user:newowner@example.com"
+      #     p.roles["roles/viewer"] = ["allUsers"]
+      #   end
+      #
+      class Policy
+        attr_reader :etag, :roles
+
+        ##
+        # @private Creates a Policy object.
+        def initialize etag, roles
+          @etag = etag
+          @roles = roles
+        end
+
+        ##
+        # Convenience method for adding a member to a binding on this policy.
+        # See [Understanding
+        # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+        # listing of primitive and curated roles.
+        # See [Binding](https://cloud.google.com/pubsub/docs/reference/rpc/google.iam.v1#binding)
+        # for a listing of values and patterns for members.
+        #
+        # @param [String] role_name A Cloud IAM role, such as
+        #   `"roles/pubsub.admin"`.
+        # @param [String] member A Cloud IAM identity, such as
+        #   `"user:owner@example.com"`.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   topic.policy do |p|
+        #     p.add "roles/owner", "user:newowner@example.com"
+        #   end
+        #
+        def add role_name, member
+          role(role_name) << member
+        end
+
+        ##
+        # Convenience method for removing a member from a binding on this
+        # policy. See [Understanding
+        # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+        # listing of primitive and curated roles. See
+        # [Binding](https://cloud.google.com/pubsub/docs/reference/rpc/google.iam.v1#binding)
+        # for a listing of values and patterns for members.
+        #
+        # @param [String] role_name A Cloud IAM role, such as
+        #   `"roles/pubsub.admin"`.
+        # @param [String] member A Cloud IAM identity, such as
+        #   `"user:owner@example.com"`.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   topic.policy do |p|
+        #     p.remove "roles/owner", "user:owner@example.com"
+        #   end
+        #
+        def remove role_name, member
+          role(role_name).delete member
+        end
+
+        ##
+        # Convenience method returning the array of members bound to a role in
+        # this policy, or an empty array if no value is present for the role in
+        # {#roles}. See [Understanding
+        # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
+        # listing of primitive and curated roles. See
+        # [Binding](https://cloud.google.com/pubsub/docs/reference/rpc/google.iam.v1#binding)
+        # for a listing of values and patterns for members.
+        #
+        # @return [Array<String>] The members strings, or an empty array.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   topic.policy do |p|
+        #     p.role("roles/viewer") << "user:viewer@example.com"
+        #   end
+        #
+        def role role_name
+          roles[role_name] ||= []
+        end
+
+        ##
+        # @private Convert the Policy to a Google::Iam::V1::Policy object.
+        def to_grpc
+          Google::Iam::V1::Policy.new(
+            etag:     etag,
+            bindings: roles.keys.map do |role_name|
+              next if roles[role_name].empty?
+              Google::Iam::V1::Binding.new(
+                role:    role_name,
+                members: roles[role_name]
+              )
+            end
+          )
+        end
+
+        ##
+        # @private New Policy from a Google::Iam::V1::Policy object.
+        def self.from_grpc grpc
+          roles = grpc.bindings.each_with_object({}) do |binding, memo|
+            memo[binding.role] = binding.members.to_a
+          end
+          new grpc.etag, roles
+        end
+      end
+    end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
+  end
+end