google-cloud-pubsub 0.20.0

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

@@ -0,0 +1,31 @@
+# Copyright 2015 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/credentials"
+
+module Google
+  module Cloud
+    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)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# Copyright 2015 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/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"
+      #
+      #   gcloud = Google::Cloud.new
+      #   pubsub = gcloud.pubsub
+      #
+      #   # Publish a message
+      #   topic = pubsub.topic "my-topic"
+      #   message = topic.publish "new-message"
+      #   puts message.data #=>  "new-message"
+      #
+      #   # Pull a message
+      #   sub = pubsub.subscription "my-topic-sub"
+      #   received_message = sub.pull.first
+      #   puts received_message.message.data #=>  "new-message"
+      #
+      class Message
+        ##
+        # @private The gRPC Google::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::Pubsub::V1::PubsubMessage.new(
+            data: String(data).encode("ASCII-8BIT"),
+            attributes: attributes)
+        end
+
+        ##
+        # The received data.
+        def data
+          @grpc.data
+        end
+
+        ##
+        # The received attributes.
+        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_method :msg_id, :message_id
+
+        ##
+        # @private New Message from a Google::Pubsub::V1::PubsubMessage object.
+        def self.from_grpc grpc
+          new.tap do |m|
+            m.instance_variable_set "@grpc", grpc
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,209 @@
+# Copyright 2016 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/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/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/reference/rpc/google.iam.v1#binding)
+      #   for a listing of values and patterns for members.
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   gcloud = Google::Cloud.new
+      #   pubsub = gcloud.pubsub
+      #   topic = pubsub.topic "my-topic"
+      #
+      #   policy = topic.policy # API call
+      #
+      #   policy.remove "roles/owner", "user:owner@example.com" # Local call
+      #   policy.add "roles/owner", "user:newowner@example.com" # Local call
+      #   policy.roles["roles/viewer"] = ["allUsers"] # Local call
+      #
+      #   topic.policy = policy # API call
+      #
+      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/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"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   policy = topic.policy # API call
+        #
+        #   policy.add "roles/owner", "user:newowner@example.com" # Local call
+        #
+        #   topic.policy = policy # API call
+        #
+        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/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"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   policy = topic.policy # API call
+        #
+        #   policy.remove "roles/owner", "user:owner@example.com" # Local call
+        #
+        #   topic.policy = policy # API call
+        #
+        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/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"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   policy = topic.policy
+        #
+        #   policy.role("roles/viewer") << "user:viewer@example.com"
+        #
+        def role role_name
+          roles[role_name] ||= []
+        end
+
+        ##
+        # Returns a deep copy of the policy.
+        #
+        # @return [Policy]
+        #
+        def deep_dup
+          dup.tap do |p|
+            roles_dup = p.roles.each_with_object({}) do |(k, v), memo|
+              memo[k] = v.dup rescue value
+            end
+            p.instance_variable_set "@roles", roles_dup
+          end
+        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
+  end
+end

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

@@ -0,0 +1,487 @@
+# Copyright 2015 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/errors"
+require "google/cloud/core/gce"
+require "google/cloud/pubsub/service"
+require "google/cloud/pubsub/credentials"
+require "google/cloud/pubsub/topic"
+
+module Google
+  module Cloud
+    module Pubsub
+      ##
+      # # Project
+      #
+      # Represents the project that pubsub messages are pushed to and pulled
+      # from. {Topic} is a named resource to which messages are sent by
+      # publishers. {Subscription} is a named resource representing the stream
+      # of messages from a single, specific topic, to be delivered to the
+      # subscribing application. {Message} is a combination of data and
+      # attributes that a publisher sends to a topic and is eventually delivered
+      # to subscribers.
+      #
+      # See {Google::Cloud#pubsub}
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   gcloud = Google::Cloud.new
+      #   pubsub = gcloud.pubsub
+      #
+      #   topic = pubsub.topic "my-topic"
+      #   topic.publish "task completed"
+      #
+      class Project
+        ##
+        # @private The gRPC Service object.
+        attr_accessor :service
+
+        ##
+        # @private Creates a new Pub/Sub Project instance.
+        def initialize service
+          @service = service
+        end
+
+        # The Pub/Sub project connected to.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new "my-todo-project",
+        #                       "/path/to/keyfile.json"
+        #   pubsub = gcloud.pubsub
+        #
+        #   pubsub.project #=> "my-todo-project"
+        #
+        def project
+          service.project
+        end
+
+        ##
+        # @private Default project.
+        def self.default_project
+          ENV["PUBSUB_PROJECT"] ||
+            ENV["GOOGLE_CLOUD_PROJECT"] ||
+            ENV["GCLOUD_PROJECT"] ||
+            Google::Cloud::Core::GCE.project_id
+        end
+
+        ##
+        # Retrieves topic by name.
+        #
+        # The topic will be created if the topic does not exist and the
+        # `autocreate` option is set to true.
+        #
+        # @param [String] topic_name Name of a topic.
+        # @param [Boolean] autocreate Flag to control whether the requested
+        #   topic will be created if it does not exist. Ignored if `skip_lookup`
+        #   is `true`. The default value is `false`.
+        # @param [String] project If the topic belongs to a project other than
+        #   the one currently connected to, the alternate project ID can be
+        #   specified here.
+        # @param [Boolean] skip_lookup Optionally create a {Topic} object
+        #   without verifying the topic resource exists on the Pub/Sub service.
+        #   Calls made on this object will raise errors if the topic resource
+        #   does not exist. Default is `false`.
+        #
+        # @return [Google::Cloud::Pubsub::Topic, nil] Returns `nil` if topic
+        #   does not exist. Will return a newly created{
+        #   Google::Cloud::Pubsub::Topic} if the topic does not exist and
+        #   `autocreate` is set to `true`.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #   topic = pubsub.topic "existing-topic"
+        #
+        # @example By default `nil` will be returned if topic does not exist.
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #   topic = pubsub.topic "non-existing-topic" #=> nil
+        #
+        # @example With the `autocreate` option set to `true`.
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #   topic = pubsub.topic "non-existing-topic", autocreate: true
+        #
+        # @example Create topic in a different project with the `project` flag.
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #   topic = pubsub.topic "another-topic", project: "another-project"
+        #
+        # @example Skip the lookup against the service with `skip_lookup`:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #   topic = pubsub.topic "another-topic", skip_lookup: true
+        #
+        def topic topic_name, autocreate: nil, project: nil, skip_lookup: nil
+          ensure_service!
+          options = { project: project }
+          return Topic.new_lazy(topic_name, service, options) if skip_lookup
+          grpc = service.get_topic topic_name
+          Topic.from_grpc grpc, service
+        rescue Google::Cloud::NotFoundError
+          return create_topic(topic_name) if autocreate
+          nil
+        end
+        alias_method :get_topic, :topic
+        alias_method :find_topic, :topic
+
+        ##
+        # Creates a new topic.
+        #
+        # @param [String] topic_name Name of a topic.
+        #
+        # @return [Google::Cloud::Pubsub::Topic]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #   topic = pubsub.create_topic "my-topic"
+        #
+        def create_topic topic_name
+          ensure_service!
+          grpc = service.create_topic topic_name
+          Topic.from_grpc grpc, service
+        end
+        alias_method :new_topic, :create_topic
+
+        ##
+        # Retrieves a list of topics for the given project.
+        #
+        # @param [String] token The `token` value returned by the last call to
+        #   `topics`; indicates that this is a continuation of a call, and that
+        #   the system should return the next page of data.
+        # @param [Integer] max Maximum number of topics to return.
+        #
+        # @return [Array<Google::Cloud::Pubsub::Topic>] (See
+        #   {Google::Cloud::Pubsub::Topic::List})
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   topics = pubsub.topics
+        #   topics.each do |topic|
+        #     puts topic.name
+        #   end
+        #
+        # @example Retrieve all topics: (See {Topic::List#all})
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   topics = pubsub.topics
+        #   topics.all do |topic|
+        #     puts topic.name
+        #   end
+        #
+        def topics token: nil, max: nil
+          ensure_service!
+          options = { token: token, max: max }
+          grpc = service.list_topics options
+          Topic::List.from_grpc grpc, service, max
+        end
+        alias_method :find_topics, :topics
+        alias_method :list_topics, :topics
+
+        ##
+        # Publishes one or more messages to the given topic. The topic will be
+        # created if the topic does previously not exist and the `autocreate`
+        # option is provided.
+        #
+        # A note about auto-creating the topic: Any message published to a topic
+        # without a subscription will be lost.
+        #
+        # @param [String] topic_name Name of a topic.
+        # @param [String, File] data The message data.
+        # @param [Hash] attributes Optional attributes for the message.
+        # @option attributes [Boolean] :autocreate Flag to control whether the
+        #   provided topic will be created if it does not exist.
+        # @yield [publisher] a block for publishing multiple messages in one
+        #   request
+        # @yieldparam [Topic::Publisher] publisher the topic publisher object
+        #
+        # @return [Message, Array<Message>] Returns the published message when
+        #   called without a block, or an array of messages when called with a
+        #   block.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   msg = pubsub.publish "my-topic", "new-message"
+        #
+        # @example A message can be published using a File object:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   msg = pubsub.publish "my-topic", File.open("message.txt")
+        #
+        # @example Additionally, a message can be published with attributes:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   msg = pubsub.publish "my-topic", "new-message", foo: :bar,
+        #                                                   this: :that
+        #
+        # @example Multiple messages can be sent at the same time using a block:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   msgs = pubsub.publish "my-topic" do |p|
+        #     p.publish "new-message-1", foo: :bar
+        #     p.publish "new-message-2", foo: :baz
+        #     p.publish "new-message-3", foo: :bif
+        #   end
+        #
+        # @example With `autocreate`:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   msg = pubsub.publish "new-topic", "new-message", autocreate: true
+        #
+        def publish topic_name, data = nil, attributes = {}
+          # Fix parameters
+          if data.is_a?(::Hash) && attributes.empty?
+            attributes = data
+            data = nil
+          end
+          # extract autocreate option
+          autocreate = attributes.delete :autocreate
+          ensure_service!
+          publisher = Topic::Publisher.new data, attributes
+          yield publisher if block_given?
+          return nil if publisher.messages.count.zero?
+          publish_batch_messages topic_name, publisher, autocreate
+        end
+
+        ##
+        # Creates a new {Subscription} object for the provided topic. The topic
+        # will be created if the topic does previously not exist and the
+        # `autocreate` option is provided.
+        #
+        # @param [String] topic_name Name of a topic.
+        # @param [String] subscription_name Name of the new subscription. Must
+        #   start with a letter, and contain only letters ([A-Za-z]), numbers
+        #   ([0-9], dashes (-), underscores (_), periods (.), tildes (~), plus
+        #   (+) or percent signs (%). It must be between 3 and 255 characters in
+        #   length, and it must not start with "goog".
+        # @param [Integer] deadline The maximum number of seconds after a
+        #   subscriber receives a message before the subscriber should
+        #   acknowledge the message.
+        # @param [String] endpoint A URL locating the endpoint to which messages
+        #   should be pushed.
+        # @param [String] autocreate Flag to control whether the topic will be
+        #   created if it does not exist.
+        #
+        # @return [Google::Cloud::Pubsub::Subscription]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   sub = pubsub.subscribe "my-topic", "my-topic-sub"
+        #   puts sub.name # => "my-topic-sub"
+        #
+        # @example The name is optional, and will be generated if not given.
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   sub = pubsub.subscribe "my-topic"
+        #   puts sub.name # => "generated-sub-name"
+        #
+        # @example Wait 2 minutes for acknowledgement and push all to endpoint:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   sub = pubsub.subscribe "my-topic", "my-topic-sub",
+        #                          deadline: 120,
+        #                          endpoint: "https://example.com/push"
+        #
+        # @example With `autocreate`:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   sub = pubsub.subscribe "new-topic", "new-topic-sub",
+        #                          autocreate: true
+        #
+        def subscribe topic_name, subscription_name, deadline: nil,
+                      endpoint: nil, autocreate: nil
+          ensure_service!
+          options = { deadline: deadline, endpoint: endpoint }
+          grpc = service.create_subscription topic_name,
+                                             subscription_name, options
+          Subscription.from_grpc grpc, service
+        rescue Google::Cloud::NotFoundError => e
+          if autocreate
+            create_topic topic_name
+            return subscribe(topic_name, subscription_name,
+                             deadline: deadline, endpoint: endpoint,
+                             autocreate: false)
+          end
+          raise e
+        end
+        alias_method :create_subscription, :subscribe
+        alias_method :new_subscription, :subscribe
+
+        ##
+        # Retrieves subscription by name.
+        #
+        # @param [String] subscription_name Name of a subscription.
+        # @param [String] project If the subscription belongs to a project other
+        #   than the one currently connected to, the alternate project ID can be
+        #   specified here.
+        # @param [Boolean] skip_lookup Optionally create a {Subscription} object
+        #   without verifying the subscription resource exists on the Pub/Sub
+        #   service. Calls made on this object will raise errors if the service
+        #   resource does not exist. Default is `false`.
+        #
+        # @return [Google::Cloud::Pubsub::Subscription, nil] Returns `nil` if
+        #   the subscription does not exist
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   subscription = pubsub.subscription "my-sub"
+        #   puts subscription.name
+        #
+        # @example Skip the lookup against the service with `skip_lookup`:
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   # No API call is made to retrieve the subscription information.
+        #   subscription = pubsub.subscription "my-sub", skip_lookup: true
+        #   puts subscription.name
+        #
+        def subscription subscription_name, project: nil, skip_lookup: nil
+          ensure_service!
+          options = { project: project }
+          if skip_lookup
+            return Subscription.new_lazy subscription_name, service, options
+          end
+          grpc = service.get_subscription subscription_name
+          Subscription.from_grpc grpc, service
+        rescue Google::Cloud::NotFoundError
+          nil
+        end
+        alias_method :get_subscription, :subscription
+        alias_method :find_subscription, :subscription
+
+        ##
+        # Retrieves a list of subscriptions for the given project.
+        #
+        # @param [String] token A previously-returned page token representing
+        #   part of the larger set of results to view.
+        # @param [Integer] max Maximum number of subscriptions to return.
+        #
+        # @return [Array<Google::Cloud::Pubsub::Subscription>] (See
+        #   {Google::Cloud::Pubsub::Subscription::List})
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   subscriptions = pubsub.subscriptions
+        #   subscriptions.each do |subscription|
+        #     puts subscription.name
+        #   end
+        #
+        # @example Retrieve all subscriptions: (See {Subscription::List#all})
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   pubsub = gcloud.pubsub
+        #
+        #   subscriptions = pubsub.subscriptions
+        #   subscriptions.all do |subscription|
+        #     puts subscription.name
+        #   end
+        #
+        def subscriptions token: nil, max: nil
+          ensure_service!
+          options = { token: token, max: max }
+          grpc = service.list_subscriptions options
+          Subscription::List.from_grpc grpc, service, max
+        end
+        alias_method :find_subscriptions, :subscriptions
+        alias_method :list_subscriptions, :subscriptions
+
+        protected
+
+        ##
+        # @private Raise an error unless an active connection to the service is
+        # available.
+        def ensure_service!
+          fail "Must have active connection to service" unless service
+        end
+
+        ##
+        # Call the publish API with arrays of data data and attrs.
+        def publish_batch_messages topic_name, batch, autocreate = false
+          grpc = service.publish topic_name, batch.messages
+          batch.to_gcloud_messages Array(grpc.message_ids)
+        rescue Google::Cloud::NotFoundError => e
+          if autocreate
+            create_topic topic_name
+            return publish_batch_messages topic_name, batch, false
+          end
+          raise e
+        end
+      end
+    end
+  end
+end