google-cloud-pubsub 0.20.0 → 2.6.1

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

@@ -1,10 +1,10 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# 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
 #
-#     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,
@@ -17,7 +17,7 @@ require "google/cloud/errors"
 
 module Google
   module Cloud
-    module Pubsub
+    module PubSub
       ##
       # # Policy
       #
@@ -27,7 +27,7 @@ module Google
       # 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}
+      # 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`
@@ -37,12 +37,12 @@ module Google
       # 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=}.
+      # {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
+      # @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
@@ -52,26 +52,24 @@ module Google
       #   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)
+      #   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"
+      #   require "google/cloud/pubsub"
       #
-      #   gcloud = Google::Cloud.new
-      #   pubsub = gcloud.pubsub
+      #   pubsub = Google::Cloud::PubSub.new
       #   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
+      #   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
+        attr_reader :etag
+        attr_reader :roles
 
         ##
         # @private Creates a Policy object.
@@ -85,7 +83,7 @@ module Google
         # 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)
+        # 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
@@ -94,17 +92,14 @@ module Google
         #   `"user:owner@example.com"`.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #   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
+        #   topic.policy do |p|
+        #     p.add "roles/owner", "user:newowner@example.com"
+        #   end
         #
         def add role_name, member
           role(role_name) << member
@@ -115,7 +110,7 @@ module Google
         # 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)
+        # [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
@@ -124,17 +119,14 @@ module Google
         #   `"user:owner@example.com"`.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #   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
+        #   topic.policy do |p|
+        #     p.remove "roles/owner", "user:owner@example.com"
+        #   end
         #
         def remove role_name, member
           role(role_name).delete member
@@ -146,52 +138,37 @@ module Google
         # {#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)
+        # [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"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #   topic = pubsub.topic "my-topic"
         #
-        #   policy = topic.policy
-        #
-        #   policy.role("roles/viewer") << "user:viewer@example.com"
+        #   topic.policy do |p|
+        #     p.role("roles/viewer") << "user:viewer@example.com"
+        #   end
         #
         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,
+            etag:     etag,
             bindings: roles.keys.map do |role_name|
               next if roles[role_name].empty?
               Google::Iam::V1::Binding.new(
-                role: role_name,
+                role:    role_name,
                 members: roles[role_name]
               )
-            end
+            end.compact
           )
         end
 
@@ -205,5 +182,7 @@ module Google
         end
       end
     end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
   end
 end

data/lib/google/cloud/pubsub/project.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,
@@ -14,14 +14,16 @@
 
 
 require "google/cloud/errors"
-require "google/cloud/core/gce"
 require "google/cloud/pubsub/service"
 require "google/cloud/pubsub/credentials"
 require "google/cloud/pubsub/topic"
+require "google/cloud/pubsub/batch_publisher"
+require "google/cloud/pubsub/schema"
+require "google/cloud/pubsub/snapshot"
 
 module Google
   module Cloud
-    module Pubsub
+    module PubSub
       ##
       # # Project
       #
@@ -36,17 +38,16 @@ module Google
       # See {Google::Cloud#pubsub}
       #
       # @example
-      #   require "google/cloud"
+      #   require "google/cloud/pubsub"
       #
-      #   gcloud = Google::Cloud.new
-      #   pubsub = gcloud.pubsub
+      #   pubsub = Google::Cloud::PubSub.new
       #
       #   topic = pubsub.topic "my-topic"
       #   topic.publish "task completed"
       #
       class Project
         ##
-        # @private The gRPC Service object.
+        # @private The Service object.
         attr_accessor :service
 
         ##
@@ -58,118 +59,191 @@ module Google
         # The Pub/Sub project connected to.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new "my-todo-project",
-        #                       "/path/to/keyfile.json"
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new(
+        #     project_id: "my-project",
+        #     credentials: "/path/to/keyfile.json"
+        #   )
         #
-        #   pubsub.project #=> "my-todo-project"
+        #   pubsub.project_id #=> "my-project"
         #
-        def project
+        def project_id
           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
+        alias project project_id
 
         ##
         # 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] topic_name Name of a topic. The value can be a simple
+        #   topic ID (relative name), in which case the current project ID will
+        #   be supplied, or a fully-qualified topic name in the form
+        #   `projects/{project_id}/topics/{topic_id}`.
         # @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.
+        #   specified here. Optional. Not used if a fully-qualified topic name
+        #   is provided for `topic_name`.
         # @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`.
+        #   does not exist. Default is `false`. Optional.
+        # @param [Hash] async A hash of values to configure the topic's
+        #   {AsyncPublisher} that is created when {Topic#publish_async}
+        #   is called. Optional.
+        #
+        #   Hash keys and values may include the following:
+        #
+        #   * `:max_bytes` (Integer) The maximum size of messages to be collected before the batch is published. Default
+        #     is 1,000,000 (1MB).
+        #   * `:max_messages` (Integer) The maximum number of messages to be collected before the batch is published.
+        #     Default is 100.
+        #   * `:interval` (Numeric) The number of seconds to collect messages before the batch is published. Default is
+        #     0.01.
+        #   * `:threads` (Hash) The number of threads to create to handle concurrent calls by the publisher:
+        #     * `:publish` (Integer) The number of threads used to publish messages. Default is 2.
+        #     * `:callback` (Integer) The number of threads to handle the published messages' callbacks. Default is 4.
+        #
+        # @return [Google::Cloud::PubSub::Topic, nil] Returns `nil` if topic
+        #   does not exist.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #   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"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
-        #   topic = pubsub.topic "non-existing-topic", autocreate: true
+        #   pubsub = Google::Cloud::PubSub.new
+        #   topic = pubsub.topic "non-existing-topic" # nil
         #
         # @example Create topic in a different project with the `project` flag.
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #   topic = pubsub.topic "another-topic", project: "another-project"
         #
         # @example Skip the lookup against the service with `skip_lookup`:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #   topic = pubsub.topic "another-topic", skip_lookup: true
         #
-        def topic topic_name, autocreate: nil, project: nil, skip_lookup: nil
+        # @example Configuring AsyncPublisher to increase concurrent callbacks:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   topic = pubsub.topic "my-topic",
+        #                        async: { threads: { callback: 16 } }
+        #
+        #   topic.publish_async "task completed" do |result|
+        #     if result.succeeded?
+        #       log_publish_success result.data
+        #     else
+        #       log_publish_failure result.data, result.error
+        #     end
+        #   end
+        #
+        #   topic.async_publisher.stop!
+        #
+        def topic topic_name, project: nil, skip_lookup: nil, async: 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
+          return Topic.from_name topic_name, service, options if skip_lookup
+          grpc = service.get_topic topic_name, options
+          Topic.from_grpc grpc, service, async: async
         rescue Google::Cloud::NotFoundError
-          return create_topic(topic_name) if autocreate
           nil
         end
-        alias_method :get_topic, :topic
-        alias_method :find_topic, :topic
+        alias get_topic topic
+        alias find_topic topic
 
         ##
         # Creates a new topic.
         #
-        # @param [String] topic_name Name of a topic.
-        #
-        # @return [Google::Cloud::Pubsub::Topic]
+        # @param [String] topic_name Name of a topic. Required.
+        #   The value can be a simple topic ID (relative name), in which
+        #   case the current project ID will be supplied, or a fully-qualified
+        #   topic name in the form `projects/{project_id}/topics/{topic_id}`.
+        #
+        #   The topic ID (relative name) 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 [Hash] labels A hash of user-provided labels associated with
+        #   the topic. You can use these to organize and group your topics.
+        #   Label keys and values can be no longer than 63 characters, can only
+        #   contain lowercase letters, numeric characters, underscores and
+        #   dashes. International characters are allowed. Label values are
+        #   optional. Label keys must start with a letter and each label in the
+        #   list must have a different key. See [Creating and Managing
+        #   Labels](https://cloud.google.com/pubsub/docs/labels).
+        # @param [String] kms_key The Cloud KMS encryption key that will be used
+        #   to protect access to messages published on this topic. Optional.
+        #   For example: `projects/a/locations/b/keyRings/c/cryptoKeys/d`
+        # @param [Array<String>] persistence_regions The list of GCP region IDs
+        #   where messages that are published to the topic may be persisted in
+        #   storage. Optional.
+        # @param [Hash] async A hash of values to configure the topic's
+        #   {AsyncPublisher} that is created when {Topic#publish_async}
+        #   is called. Optional.
+        #
+        #   Hash keys and values may include the following:
+        #
+        #   * `:max_bytes` (Integer) The maximum size of messages to be collected
+        #     before the batch is published. Default is 1,000,000 (1MB).
+        #   * `:max_messages` (Integer) The maximum number of messages to be
+        #     collected before the batch is published. Default is 100.
+        #   * `:interval` (Numeric) The number of seconds to collect messages before
+        #     the batch is published. Default is 0.01.
+        #   * `:threads` (Hash) The number of threads to create to handle concurrent
+        #     calls by the publisher:
+        #
+        #     * `:publish` (Integer) The number of threads used to publish messages.
+        #       Default is 2.
+        #     * `:callback` (Integer) The number of threads to handle the published
+        #       messages' callbacks. Default is 4.
+        # @param [String] schema_name The name of the schema that messages
+        #   published should be validated against. Optional. The value can be a
+        #   simple schema ID (relative name), in which case the current project
+        #   ID will be supplied, or a fully-qualified schema name in the form
+        #   `projects/{project_id}/schemas/{schema_id}`. If provided,
+        #   `message_encoding` must also be provided.
+        # @param [String, Symbol] message_encoding The encoding of messages validated
+        #   against the schema identified by `schema_name`. Optional. Values include:
+        #
+        #   * `JSON` - JSON encoding.
+        #   * `BINARY` - Binary encoding, as defined by the schema type. For some
+        #     schema types, binary encoding may not be available.
+        #
+        # @return [Google::Cloud::PubSub::Topic]
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #   topic = pubsub.create_topic "my-topic"
         #
-        def create_topic topic_name
+        def create_topic topic_name,
+                         labels: nil,
+                         kms_key: nil,
+                         persistence_regions: nil,
+                         async: nil,
+                         schema_name: nil,
+                         message_encoding: nil
           ensure_service!
-          grpc = service.create_topic topic_name
-          Topic.from_grpc grpc, service
+          grpc = service.create_topic topic_name,
+                                      labels:              labels,
+                                      kms_key_name:        kms_key,
+                                      persistence_regions: persistence_regions,
+                                      schema_name:         schema_name,
+                                      message_encoding:    message_encoding
+          Topic.from_grpc grpc, service, async: async
         end
-        alias_method :new_topic, :create_topic
+        alias new_topic create_topic
 
         ##
         # Retrieves a list of topics for the given project.
@@ -179,14 +253,13 @@ module Google
         #   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})
+        # @return [Array<Google::Cloud::PubSub::Topic>] (See
+        #   {Google::Cloud::PubSub::Topic::List})
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #
         #   topics = pubsub.topics
         #   topics.each do |topic|
@@ -194,10 +267,9 @@ module Google
         #   end
         #
         # @example Retrieve all topics: (See {Topic::List#all})
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #
         #   topics = pubsub.topics
         #   topics.all do |topic|
@@ -210,255 +282,327 @@ module Google
           grpc = service.list_topics options
           Topic::List.from_grpc grpc, service, max
         end
-        alias_method :find_topics, :topics
-        alias_method :list_topics, :topics
+        alias find_topics topics
+        alias 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.
+        # Retrieves subscription by name.
+        #
+        # @param [String] subscription_name Name of a subscription. The value can
+        #   be a simple subscription ID, in which case the current project ID
+        #   will be supplied, or a fully-qualified subscription name in the form
+        #   `projects/{project_id}/subscriptions/{subscription_id}`.
+        # @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. Not used if a fully-qualified subscription name is
+        #   provided for `subscription_name`.
+        # @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"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #
-        #   msg = pubsub.publish "my-topic", "new-message"
+        #   sub = pubsub.subscription "my-sub"
+        #   sub.name #=> "projects/my-project/subscriptions/my-sub"
         #
-        # @example A message can be published using a File object:
-        #   require "google/cloud"
+        # @example Skip the lookup against the service with `skip_lookup`:
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #
-        #   msg = pubsub.publish "my-topic", File.open("message.txt")
+        #   # No API call is made to retrieve the subscription information.
+        #   sub = pubsub.subscription "my-sub", skip_lookup: true
+        #   sub.name #=> "projects/my-project/subscriptions/my-sub"
         #
-        # @example Additionally, a message can be published with attributes:
-        #   require "google/cloud"
+        def subscription subscription_name, project: nil, skip_lookup: nil
+          ensure_service!
+          options = { project: project }
+          return Subscription.from_name subscription_name, service, options if skip_lookup
+          grpc = service.get_subscription subscription_name, options
+          Subscription.from_grpc grpc, service
+        rescue Google::Cloud::NotFoundError
+          nil
+        end
+        alias get_subscription subscription
+        alias find_subscription subscription
+
+        ##
+        # Retrieves a list of subscriptions for the given project.
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        # @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.
         #
-        #   msg = pubsub.publish "my-topic", "new-message", foo: :bar,
-        #                                                   this: :that
+        # @return [Array<Google::Cloud::PubSub::Subscription>] (See
+        #   {Google::Cloud::PubSub::Subscription::List})
         #
-        # @example Multiple messages can be sent at the same time using a block:
-        #   require "google/cloud"
+        # @example
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #
-        #   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
+        #   subs = pubsub.subscriptions
+        #   subs.each do |sub|
+        #     puts sub.name
         #   end
         #
-        # @example With `autocreate`:
-        #   require "google/cloud"
+        # @example Retrieve all subscriptions: (See {Subscription::List#all})
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #
-        #   msg = pubsub.publish "new-topic", "new-message", autocreate: true
+        #   subs = pubsub.subscriptions
+        #   subs.all do |sub|
+        #     puts sub.name
+        #   end
         #
-        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
+        def subscriptions token: nil, max: nil
           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
+          options = { token: token, max: max }
+          grpc = service.list_subscriptions options
+          Subscription::List.from_grpc grpc, service, max
         end
+        alias find_subscriptions subscriptions
+        alias list_subscriptions subscriptions
+
 
         ##
-        # 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]
+        # Retrieves a list of snapshots for the given project.
         #
-        # @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
+        # @param [String] token A previously-returned page token representing
+        #   part of the larger set of results to view.
+        # @param [Integer] max Maximum number of snapshots to return.
         #
-        #   sub = pubsub.subscribe "my-topic"
-        #   puts sub.name # => "generated-sub-name"
+        # @return [Array<Google::Cloud::PubSub::Snapshot>] (See
+        #   {Google::Cloud::PubSub::Snapshot::List})
         #
-        # @example Wait 2 minutes for acknowledgement and push all to endpoint:
-        #   require "google/cloud"
+        # @example
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #
-        #   sub = pubsub.subscribe "my-topic", "my-topic-sub",
-        #                          deadline: 120,
-        #                          endpoint: "https://example.com/push"
+        #   snapshots = pubsub.snapshots
+        #   snapshots.each do |snapshot|
+        #     puts snapshot.name
+        #   end
         #
-        # @example With `autocreate`:
-        #   require "google/cloud"
+        # @example Retrieve all snapshots: (See {Snapshot::List#all})
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #
-        #   sub = pubsub.subscribe "new-topic", "new-topic-sub",
-        #                          autocreate: true
+        #   snapshots = pubsub.snapshots
+        #   snapshots.all do |snapshot|
+        #     puts snapshot.name
+        #   end
         #
-        def subscribe topic_name, subscription_name, deadline: nil,
-                      endpoint: nil, autocreate: nil
+        def snapshots token: nil, max: 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
+          options = { token: token, max: max }
+          grpc = service.list_snapshots options
+          Snapshot::List.from_grpc grpc, service, max
         end
-        alias_method :create_subscription, :subscribe
-        alias_method :new_subscription, :subscribe
+        alias find_snapshots snapshots
+        alias list_snapshots snapshots
 
         ##
-        # Retrieves subscription by name.
-        #
-        # @param [String] subscription_name Name of a subscription.
-        # @param [String] project If the subscription belongs to a project other
+        # Retrieves schema by name.
+        #
+        # @param [String] schema_name Name of a schema. The value can
+        #   be a simple schema ID, in which case the current project ID
+        #   will be supplied, or a fully-qualified schema name in the form
+        #   `projects/{project_id}/schemas/{schema_id}`.
+        # @param view [Symbol, String, nil] Possible values:
+        #   * `BASIC` - Include the `name` and `type` of the schema, but not the `definition`.
+        #   * `FULL` - Include all Schema object fields.
+        #
+        #   The default value is `BASIC`.
+        # @param [String] project If the schema 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
+        #   specified here. Not used if a fully-qualified schema name is
+        #   provided for `schema_name`.
+        # @param [Boolean] skip_lookup Optionally create a {Schema} object
+        #   without verifying the schema 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
+        # @return [Google::Cloud::PubSub::Schema, nil] Returns `nil` if
+        #   the schema does not exist.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #
-        #   subscription = pubsub.subscription "my-sub"
-        #   puts subscription.name
+        #   schema = pubsub.schema "my-schema"
+        #   schema.name #=> "projects/my-project/schemas/my-schema"
+        #   schema.type #=> :PROTOCOL_BUFFER
+        #   # schema.definition # nil - Use view: :full to load complete resource.
         #
         # @example Skip the lookup against the service with `skip_lookup`:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #
-        #   # No API call is made to retrieve the subscription information.
-        #   subscription = pubsub.subscription "my-sub", skip_lookup: true
-        #   puts subscription.name
+        #   # No API call is made to retrieve the schema information.
+        #   # The default project is used in the name.
+        #   schema = pubsub.schema "my-schema", skip_lookup: true
+        #   schema.name #=> "projects/my-project/schemas/my-schema"
+        #   schema.type #=> nil
+        #   schema.definition #=> nil
         #
-        def subscription subscription_name, project: nil, skip_lookup: nil
+        # @example Get the schema definition with `view: :full`:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   schema = pubsub.schema "my-schema", view: :full
+        #   schema.name #=> "projects/my-project/schemas/my-schema"
+        #   schema.type #=> :PROTOCOL_BUFFER
+        #   schema.definition # The schema definition
+        #
+        def schema schema_name, view: nil, 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
+          return Schema.from_name schema_name, view, service, options if skip_lookup
+          view ||= :BASIC
+          grpc = service.get_schema schema_name, view, options
+          Schema.from_grpc grpc, service
         rescue Google::Cloud::NotFoundError
           nil
         end
-        alias_method :get_subscription, :subscription
-        alias_method :find_subscription, :subscription
+        alias get_schema schema
+        alias find_schema schema
 
         ##
-        # Retrieves a list of subscriptions for the given project.
+        # Creates a new schema.
+        #
+        # @param [String] schema_id The ID to use for the schema, which will
+        #   become the final component of the schema's resource name. Required.
+        #
+        #   The schema ID (relative name) 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 [String, Symbol] type The type of the schema. Required. Possible
+        #   values are case-insensitive and include:
+        #
+        #     * `PROTOCOL_BUFFER` - A Protocol Buffer schema definition.
+        #     * `AVRO` - An Avro schema definition.
+        # @param [String] definition  The definition of the schema. Required. This
+        #   should be a string representing the full definition of the schema that
+        #   is a valid schema definition of the type specified in `type`.
+        # @param [String] project If the schema belongs to a project other
+        #   than the one currently connected to, the alternate project ID can be
+        #   specified here. Optional.
         #
+        # @return [Google::Cloud::PubSub::Schema]
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   definition = "..."
+        #   schema = pubsub.create_schema "my-schema", :avro, definition
+        #   schema.name #=> "projects/my-project/schemas/my-schema"
+        #
+        def create_schema schema_id, type, definition, project: nil
+          ensure_service!
+          type = type.to_s.upcase
+          grpc = service.create_schema schema_id, type, definition, project: project
+          Schema.from_grpc grpc, service
+        end
+        alias new_schema create_schema
+
+        ##
+        # Retrieves a list of schemas for the given project.
+        #
+        # @param view [String, Symbol, nil] The set of fields to return in the response. Possible values:
+        #
+        #     * `BASIC` - Include the `name` and `type` of the schema, but not the `definition`.
+        #     * `FULL` - Include all Schema object fields.
+        #
+        #   The default value is `BASIC`.
         # @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.
+        # @param [Integer] max Maximum number of schemas to return.
         #
-        # @return [Array<Google::Cloud::Pubsub::Subscription>] (See
-        #   {Google::Cloud::Pubsub::Subscription::List})
+        # @return [Array<Google::Cloud::PubSub::Schema>] (See
+        #   {Google::Cloud::PubSub::Schema::List})
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #
-        #   subscriptions = pubsub.subscriptions
-        #   subscriptions.each do |subscription|
-        #     puts subscription.name
+        #   schemas = pubsub.schemas
+        #   schemas.each do |schema|
+        #     puts schema.name
         #   end
         #
-        # @example Retrieve all subscriptions: (See {Subscription::List#all})
-        #   require "google/cloud"
+        # @example Retrieve all schemas: (See {Schema::List#all})
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::PubSub.new
         #
-        #   subscriptions = pubsub.subscriptions
-        #   subscriptions.all do |subscription|
-        #     puts subscription.name
+        #   schemas = pubsub.schemas
+        #   schemas.all do |schema|
+        #     puts schema.name
         #   end
         #
-        def subscriptions token: nil, max: nil
+        def schemas view: nil, token: nil, max: nil
           ensure_service!
+          view ||= :BASIC
           options = { token: token, max: max }
-          grpc = service.list_subscriptions options
-          Subscription::List.from_grpc grpc, service, max
+          grpc = service.list_schemas view, options
+          Schema::List.from_grpc grpc, service, view, max
         end
-        alias_method :find_subscriptions, :subscriptions
-        alias_method :list_subscriptions, :subscriptions
+        alias find_schemas schemas
+        alias list_schemas schemas
+
+        ##
+        # Validates a schema type and definition.
+        #
+        # @param [String, Symbol] type The type of the schema. Required. Possible
+        #   values are case-insensitive and include:
+        #
+        #     * `PROTOCOL_BUFFER` - A Protocol Buffer schema definition.
+        #     * `AVRO` - An Avro schema definition.
+        # @param [String] definition  The definition of the schema. Required. This
+        #   should be a string representing the full definition of the schema that
+        #   is a valid schema definition of the type specified in `type`.
+        # @param [String] project If the schema belongs to a project other
+        #   than the one currently connected to, the alternate project ID can be
+        #   specified here. Optional.
+        #
+        # @return [Boolean] `true` if the schema is valid, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   definition = "..."
+        #   pubsub.validate_schema :avro, definition #=> true
+        #
+        def valid_schema? type, definition, project: nil
+          ensure_service!
+          type = type.to_s.upcase
+          service.validate_schema type, definition, project: project # return type is empty
+          true
+        rescue Google::Cloud::InvalidArgumentError
+          false
+        end
+        alias validate_schema valid_schema?
 
         protected
 
@@ -466,22 +610,18 @@ module Google
         # @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
+          raise "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
+        def publish_batch_messages topic_name, batch
           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
+
+    Pubsub = PubSub unless const_defined? :Pubsub
   end
 end