google-cloud-pubsub 2.4.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4148f77602c7b9031ed772a14735b25414034684472928fb5244a3c07c2c080
-  data.tar.gz: 247fd6d4697c8e4f04858487441a3552f30ebe3010720861a1e2c9e8198de219
+  metadata.gz: 00a75b823e392ec6afe50d693ae28a42833c2b40f06e8fa8311dff1cbafcc2df
+  data.tar.gz: d1caf14295648c05ac0f067832f1c7c8c51ee8638da47c49d3d5af6ad26ce23f
 SHA512:
-  metadata.gz: c926ed2d0bca88e81a0545e86ca4fdd916df9d24f1108e4e74cf9140c0a835b79fb6fc207074d62a920de0958e69071235d0c8874970aae9db3657e24c36b2e1
-  data.tar.gz: 3f719066bf2ffc015b88dd0ffc5f13c38d853c2e54603daa6190905420a87b4aeb9372e4d1bcb37d68863ac38151d147d465ec3891333608718ede84123dca92
+  metadata.gz: 82745cfef6ebc3a5dae4bb44168660c6525ea2a2cac5d16f0087b8791d472a2d3eff5961627bf0ae7701a7f731715a21049b2da80ab551516c8e8da98aa31e6c
+  data.tar.gz: e9e2671fcf438f9cc5e7a5baa7cba1a1bb44fa5955bcad7a8ebaaffa111391457ea4d218a173c8f67b6a327e5f622406c20bd223c4799a5720008a5a99eda3c6

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Release History
 
+### 2.5.0 / 2021-04-01
+
+#### Features
+
+* Add Schema support
+  * Add Schema
+  * Add Project#create_schema
+  * Add Project#schema
+  * Add Project#schemas (Schema::List)
+  * Add Project#valid_schema?
+  * Add schema options to Project#create_topic
+  * Add Topic#schema_name
+  * Add Topic#message_encoding
+  * Add Topic#message_encoding_binary?
+  * Add Topic#message_encoding_json?
+
 ### 2.4.0 / 2021-03-10
 
 #### Features

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

@@ -18,6 +18,7 @@ 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
@@ -192,15 +193,31 @@ module Google
         #
         #   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.
+        #   * `: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]
         #
@@ -210,12 +227,20 @@ module Google
         #   pubsub = Google::Cloud::PubSub.new
         #   topic = pubsub.create_topic "my-topic"
         #
-        def create_topic topic_name, labels: nil, kms_key: nil, persistence_regions: nil, async: nil
+        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,
                                       labels:              labels,
                                       kms_key_name:        kms_key,
-                                      persistence_regions: persistence_regions
+                                      persistence_regions: persistence_regions,
+                                      schema_name:         schema_name,
+                                      message_encoding:    message_encoding
           Topic.from_grpc grpc, service, async: async
         end
         alias new_topic create_topic
@@ -387,6 +412,198 @@ module Google
         alias find_snapshots snapshots
         alias list_snapshots snapshots
 
+        ##
+        # 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. 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::Schema, nil] Returns `nil` if
+        #   the schema does not exist.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   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/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   # 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
+        #
+        # @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 }
+          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 get_schema schema
+        alias find_schema schema
+
+        ##
+        # 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 schemas to return.
+        #
+        # @return [Array<Google::Cloud::PubSub::Schema>] (See
+        #   {Google::Cloud::PubSub::Schema::List})
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   schemas = pubsub.schemas
+        #   schemas.each do |schema|
+        #     puts schema.name
+        #   end
+        #
+        # @example Retrieve all schemas: (See {Schema::List#all})
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   schemas = pubsub.schemas
+        #   schemas.all do |schema|
+        #     puts schema.name
+        #   end
+        #
+        def schemas view: nil, token: nil, max: nil
+          ensure_service!
+          view ||= :BASIC
+          options = { token: token, max: max }
+          grpc = service.list_schemas view, options
+          Schema::List.from_grpc grpc, service, view, max
+        end
+        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
 
         ##

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

@@ -0,0 +1,310 @@
+# Copyright 2021 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/schema/list"
+require "google/cloud/pubsub/v1"
+
+module Google
+  module Cloud
+    module PubSub
+      ##
+      # # Schema
+      #
+      # A schema resource.
+      #
+      # @example
+      #   require "google/cloud/pubsub"
+      #
+      #   pubsub = Google::Cloud::PubSub.new
+      #
+      #   schema = pubsub.schema "my-schema"
+      #   schema.name #=> "projects/my-project/schemas/my-schema"
+      #   schema.type #=> :PROTOCOL_BUFFER
+      #
+      class Schema
+        ##
+        # @private The Service object.
+        attr_accessor :service
+
+        ##
+        # @private The gRPC Google::Cloud::PubSub::V1::Schema object.
+        attr_accessor :grpc
+
+        ##
+        # @private Create a new Schema instance.
+        def initialize grpc, service, view: nil
+          @grpc = grpc
+          @service = service
+          @exists = nil
+          @view = view || :BASIC
+        end
+
+        ##
+        # The name of the schema.
+        #
+        # @return [String] A fully-qualified schema name in the form `projects/{project_id}/schemas/{schema_id}`.
+        #
+        def name
+          @grpc.name
+        end
+
+        ##
+        # The type of the schema. Possible values include:
+        #
+        #   * `PROTOCOL_BUFFER` - A Protocol Buffer schema definition.
+        #   * `AVRO` - An Avro schema definition.
+        #
+        # @return [String, nil] The upper-case type name.
+        #
+        def type
+          return nil if reference?
+          @grpc.type
+        end
+
+        ##
+        # The definition of the schema. This should be a string representing the full definition of the schema that is a
+        # valid schema definition of the type specified in {#type}.
+        #
+        # @return [String, nil] The schema definition.
+        #
+        def definition
+          return nil if reference?
+          @grpc.definition
+        end
+
+        ##
+        # Validates a message against a schema.
+        #
+        # @param message_data [String] Message to validate against the provided `schema_spec`.
+        # @param message_encoding [Symbol, String] The encoding of the message validated against the schema. 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 [Boolean] Returns `true` if the message validiation succeeds, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   schema = pubsub.schema "my-schema"
+        #
+        #   message_data = { "name" => "Alaska", "post_abbr" => "AK" }.to_json
+        #   schema.validate_message message_data, :json
+        #
+        def validate_message message_data, message_encoding
+          message_encoding = message_encoding.to_s.upcase
+          service.validate_message message_data, message_encoding, schema_name: name
+          true
+        rescue Google::Cloud::InvalidArgumentError
+          false
+        end
+
+        ##
+        # Removes the schema, if it exists.
+        #
+        # @return [Boolean] Returns `true` if the schema was deleted.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   schema = pubsub.schema "my-schema"
+        #
+        #   schema.delete
+        #
+        def delete
+          ensure_service!
+          service.delete_schema name
+          true
+        end
+
+        ##
+        # Reloads the schema with current data from the Pub/Sub service.
+        #
+        # @param view [Symbol, String, 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.
+        #
+        #   Optional. If not provided or `nil`, the last non-nil `view` argument to this method will be used if one has
+        #   been given, othewise `BASIC` will be used.
+        #
+        # @return [Google::Cloud::PubSub::Schema] Returns the reloaded schema.
+        #
+        # @example Skip retrieving the schema from the service, then load it:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   schema = pubsub.schema "my-schema", skip_lookup: true
+        #
+        #   schema.reload!
+        #
+        # @example Use the `view` option to load the full resource:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   schema = pubsub.schema "my-schema", view: :basic
+        #   schema.resource_partial? #=> true
+        #
+        #   schema.reload! view: :full
+        #   schema.resource_partial? #=> false
+        #
+        # @!group Lifecycle
+        #
+        def reload! view: nil
+          ensure_service!
+          @view = view || @view
+          @grpc = service.get_schema name, @view
+          @reference = nil
+          @exists = nil
+          self
+        end
+        alias refresh! reload!
+
+        ##
+        # Determines whether the schema exists in the Pub/Sub service.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   schema = pubsub.schema "my-schema"
+        #   schema.exists? #=> true
+        #
+        def exists?
+          # Always true if the object is not set as reference
+          return true unless reference?
+          # If we have a value, return it
+          return @exists unless @exists.nil?
+          ensure_grpc!
+          @exists = true
+        rescue Google::Cloud::NotFoundError
+          @exists = false
+        end
+
+        ##
+        # Determines whether the schema object was created without retrieving the
+        # resource representation from the Pub/Sub service.
+        #
+        # @return [Boolean] `true` when the schema was created without a resource
+        #   representation, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   schema = pubsub.schema "my-schema", skip_lookup: true
+        #   schema.reference? #=> true
+        #
+        def reference?
+          @grpc.type.nil? || @grpc.type == :TYPE_UNSPECIFIED
+        end
+
+        ##
+        # Determines whether the schema object was created with a resource
+        # representation from the Pub/Sub service.
+        #
+        # @return [Boolean] `true` when the schema was created with a resource
+        #   representation, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   schema = pubsub.schema "my-schema"
+        #   schema.resource? #=> true
+        #
+        def resource?
+          !reference?
+        end
+
+        ##
+        # Whether the schema was created with a partial resource representation
+        # from the Pub/Sub service.
+        #
+        # @return [Boolean] `true` when the schema was created with a partial
+        #   resource representation, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   schema = pubsub.schema "my-schema", view: :basic
+        #
+        #   schema.resource_partial? #=> true
+        #   schema.reload! view: :full # Loads the full resource.
+        #   schema.resource_partial? #=> false
+        #
+        def resource_partial?
+          resource? && !resource_full?
+        end
+
+        ##
+        # Whether the schema was created with a full resource representation
+        # from the Pub/Sub service.
+        #
+        # @return [Boolean] `true` when the schema was created with a full
+        #   resource representation, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #   schema = pubsub.schema "my-schema", view: :full
+        #
+        #   schema.resource_full? #=> true
+        #
+        def resource_full?
+          resource? && @grpc.definition && !@grpc.definition.empty?
+        end
+
+        ##
+        # @private New Schema from a Google::Cloud::PubSub::V1::Schema object.
+        def self.from_grpc grpc, service, view: nil
+          new grpc, service, view: view
+        end
+
+        ##
+        # @private New reference Schema object without making an HTTP request.
+        def self.from_name name, view, service, options = {}
+          grpc = Google::Cloud::PubSub::V1::Schema.new name: service.schema_path(name, options)
+          from_grpc grpc, service, view: view
+        end
+
+        protected
+
+        ##
+        # @private Raise an error unless an active connection to the service is available.
+        def ensure_service!
+          raise "Must have active connection to service" unless service
+        end
+
+        ##
+        # Ensures a Google::Cloud::PubSub::V1::Schema object exists.
+        def ensure_grpc!
+          ensure_service!
+          reload! if reference?
+        end
+      end
+    end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
+  end
+end

data/lib/google/cloud/pubsub/schema/list.rb

@@ -0,0 +1,180 @@
+# Copyright 2021 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 "delegate"
+
+module Google
+  module Cloud
+    module PubSub
+      class Schema
+        ##
+        # Schema::List is a special case Array with additional values.
+        class List < DelegateClass(::Array)
+          ##
+          # If not empty, indicates that there are more schemas
+          # that match the request and this value should be passed to
+          # the next {Google::Cloud::PubSub::Project#schemas} to continue.
+          attr_accessor :token
+
+          ##
+          # @private Create a new Schema::List with an array of values.
+          def initialize arr = []
+            @prefix = nil
+            @token = nil
+            @view = nil
+            @max = nil
+            super arr
+          end
+
+          ##
+          # Whether there a next page of schemas.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::PubSub.new
+          #
+          #   schemas = pubsub.schemas
+          #   if schemas.next?
+          #     next_schemas = schemas.next
+          #   end
+          #
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieve the next page of schemas.
+          #
+          # @return [Schema::List]
+          #
+          # @example
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::PubSub.new
+          #
+          #   schemas = pubsub.schemas
+          #   if schemas.next?
+          #     next_schemas = schemas.next
+          #   end
+          #
+          def next
+            return nil unless next?
+            ensure_service!
+            next_schemas
+          end
+
+          ##
+          # Retrieves remaining results by repeatedly invoking {#next} until
+          # {#next?} returns `false`. Calls the given block once for each
+          # result, which is passed as the argument to the block.
+          #
+          # An Enumerator is returned if no block is given.
+          #
+          # This method will make repeated API calls until all remaining results
+          # are retrieved. (Unlike `#each`, for example, which merely iterates
+          # over the results returned by a single API call.) Use with caution.
+          #
+          # @param [Integer] request_limit The upper limit of API requests to
+          #   make to load all schemas. Default is no limit.
+          # @yield [schema] The block for accessing each schema.
+          # @yieldparam [Schema] schema The schema object.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each schema by passing a block:
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::PubSub.new
+          #
+          #   schemas = pubsub.schemas
+          #   schemas.all do |schema|
+          #     puts schema.name
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::PubSub.new
+          #
+          #   schemas = pubsub.schemas
+          #   all_names = schemas.all.map do |schema|
+          #     schema.name
+          #   end
+          #
+          # @example Limit the number of API calls made:
+          #   require "google/cloud/pubsub"
+          #
+          #   pubsub = Google::Cloud::PubSub.new
+          #
+          #   schemas = pubsub.schemas
+          #   schemas.all(request_limit: 10) do |schema|
+          #     puts schema.name
+          #   end
+          #
+          def all request_limit: nil, &block
+            request_limit = request_limit.to_i if request_limit
+            return enum_for :all, request_limit: request_limit unless block_given?
+            results = self
+            loop do
+              results.each(&block)
+              if request_limit
+                request_limit -= 1
+                break if request_limit.negative?
+              end
+              break unless results.next?
+              results = results.next
+            end
+          end
+
+          ##
+          # @private New Schemas::List from a
+          # Google::Cloud::PubSub::V1::ListSchemasRequest object.
+          def self.from_grpc grpc_list, service, view, max = nil
+            subs = new(Array(grpc_list.schemas).map do |grpc|
+              Schema.from_grpc grpc, service
+            end)
+            token = grpc_list.next_page_token
+            token = nil if token == "".freeze
+            subs.instance_variable_set :@token,   token
+            subs.instance_variable_set :@service, service
+            subs.instance_variable_set :@view,    view
+            subs.instance_variable_set :@max,     max
+            subs
+          end
+
+          protected
+
+          ##
+          # @private Raise an error unless an active connection to the service
+          # is available.
+          def ensure_service!
+            raise "Must have active connection to service" unless @service
+          end
+
+          def next_schemas
+            options = { prefix: @prefix, token: @token, max: @max }
+            grpc = @service.list_schemas @view, options
+            self.class.from_grpc grpc, @service, @view, @max
+          end
+        end
+      end
+    end
+
+    Pubsub = PubSub unless const_defined? :Pubsub
+  end
+end

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

@@ -49,49 +49,56 @@ module Google
 
         def subscriber
           return mocked_subscriber if mocked_subscriber
-          @subscriber ||= begin
-            V1::Subscriber::Client.new do |config|
-              config.credentials = credentials if credentials
-              config.timeout = timeout if timeout
-              config.endpoint = host if host
-              config.lib_name = "gccl"
-              config.lib_version = Google::Cloud::PubSub::VERSION
-              config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}" }
-            end
+          @subscriber ||= V1::Subscriber::Client.new do |config|
+            config.credentials = credentials if credentials
+            config.timeout = timeout if timeout
+            config.endpoint = host if host
+            config.lib_name = "gccl"
+            config.lib_version = Google::Cloud::PubSub::VERSION
+            config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}" }
           end
         end
         attr_accessor :mocked_subscriber
 
         def publisher
           return mocked_publisher if mocked_publisher
-          @publisher ||= begin
-            V1::Publisher::Client.new do |config|
-              config.credentials = credentials if credentials
-              config.timeout = timeout if timeout
-              config.endpoint = host if host
-              config.lib_name = "gccl"
-              config.lib_version = Google::Cloud::PubSub::VERSION
-              config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}" }
-            end
+          @publisher ||= V1::Publisher::Client.new do |config|
+            config.credentials = credentials if credentials
+            config.timeout = timeout if timeout
+            config.endpoint = host if host
+            config.lib_name = "gccl"
+            config.lib_version = Google::Cloud::PubSub::VERSION
+            config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}" }
           end
         end
         attr_accessor :mocked_publisher
 
         def iam
           return mocked_iam if mocked_iam
-          @iam ||= begin
-            V1::IAMPolicy::Client.new do |config|
-              config.credentials = credentials if credentials
-              config.timeout = timeout if timeout
-              config.endpoint = host if host
-              config.lib_name = "gccl"
-              config.lib_version = Google::Cloud::PubSub::VERSION
-              config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
-            end
+          @iam ||= V1::IAMPolicy::Client.new do |config|
+            config.credentials = credentials if credentials
+            config.timeout = timeout if timeout
+            config.endpoint = host if host
+            config.lib_name = "gccl"
+            config.lib_version = Google::Cloud::PubSub::VERSION
+            config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
           end
         end
         attr_accessor :mocked_iam
 
+        def schemas
+          return mocked_schemas if mocked_schemas
+          @schemas ||= V1::SchemaService::Client.new do |config|
+            config.credentials = credentials if credentials
+            config.timeout = timeout if timeout
+            config.endpoint = host if host
+            config.lib_name = "gccl"
+            config.lib_version = Google::Cloud::PubSub::VERSION
+            config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+          end
+        end
+        attr_accessor :mocked_schemas
+
         ##
         # Gets the configuration of a topic.
         # Since the topic only has the name attribute,
@@ -114,18 +121,35 @@ module Google
 
         ##
         # Creates the given topic with the given name.
-        def create_topic topic_name, labels: nil, kms_key_name: nil, persistence_regions: nil, options: {}
+        def create_topic topic_name,
+                         labels: nil,
+                         kms_key_name: nil,
+                         persistence_regions: nil,
+                         schema_name: nil,
+                         message_encoding: nil,
+                         options: {}
           if persistence_regions
-            message_storage_policy = {
+            message_storage_policy = Google::Cloud::PubSub::V1::MessageStoragePolicy.new(
               allowed_persistence_regions: Array(persistence_regions)
-            }
+            )
+          end
+
+          if schema_name || message_encoding
+            unless schema_name && message_encoding
+              raise ArgumentError, "Schema settings must include both schema_name and message_encoding."
+            end
+            schema_settings = Google::Cloud::PubSub::V1::SchemaSettings.new(
+              schema:   schema_path(schema_name),
+              encoding: message_encoding.to_s.upcase
+            )
           end
 
           publisher.create_topic \
             name:                   topic_path(topic_name, options),
             labels:                 labels,
             kms_key_name:           kms_key_name,
-            message_storage_policy: message_storage_policy
+            message_storage_policy: message_storage_policy,
+            schema_settings:        schema_settings
         end
 
         def update_topic topic_obj, *fields
@@ -297,6 +321,89 @@ module Google
           end
         end
 
+        ##
+        # Lists schemas in the current (or given) project.
+        # @param view [String, Symbol, nil] Possible values:
+        #   * `BASIC` - Include the name and type of the schema, but not the definition.
+        #   * `FULL` - Include all Schema object fields.
+        #
+        def list_schemas view, options = {}
+          schema_view = Google::Cloud::PubSub::V1::SchemaView.const_get view.to_s.upcase
+          paged_enum = schemas.list_schemas parent:     project_path(options),
+                                            view:       schema_view,
+                                            page_size:  options[:max],
+                                            page_token: options[:token]
+
+          paged_enum.response
+        end
+
+        ##
+        # Creates a schema in the current (or given) project.
+        def create_schema schema_id, type, definition, options = {}
+          schema = Google::Cloud::PubSub::V1::Schema.new(
+            type:       type,
+            definition: definition
+          )
+          schemas.create_schema parent:    project_path(options),
+                                schema:    schema,
+                                schema_id: schema_id
+        end
+
+        ##
+        # Gets the details of a schema.
+        # @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.
+        #
+        def get_schema schema_name, view, options = {}
+          schema_view = Google::Cloud::PubSub::V1::SchemaView.const_get view.to_s.upcase
+          schemas.get_schema name: schema_path(schema_name, options),
+                             view: schema_view
+        end
+
+        ##
+        # Delete a schema.
+        def delete_schema schema_name
+          schemas.delete_schema name: schema_path(schema_name)
+        end
+
+        ##
+        # Validate the definition string intended for a schema.
+        def validate_schema type, definition, options = {}
+          schema = Google::Cloud::PubSub::V1::Schema.new(
+            type:       type,
+            definition: definition
+          )
+          schemas.validate_schema parent: project_path(options),
+                                  schema: schema
+        end
+
+        ##
+        # Validates a message against a schema.
+        #
+        # @param message_data [String] Message to validate against the provided `schema_spec`.
+        # @param message_encoding [Google::Cloud::PubSub::V1::Encoding] The encoding expected for messages.
+        # @param schema_name [String] Name of the schema against which to validate.
+        # @param project [String] Name of the project if not the default project.
+        # @param type [String] Ad-hoc schema type against which to validate.
+        # @param definition [String] Ad-hoc schema definition against which to validate.
+        #
+        def validate_message message_data, message_encoding, schema_name: nil, project: nil, type: nil, definition: nil
+          if type && definition
+            schema = Google::Cloud::PubSub::V1::Schema.new(
+              type:       type,
+              definition: definition
+            )
+          end
+          schemas.validate_message parent:   project_path(project: project),
+                                   name:     schema_path(schema_name),
+                                   schema:   schema,
+                                   message:  message_data,
+                                   encoding: message_encoding
+        end
+
+        # Helper methods
+
         def get_topic_policy topic_name, options = {}
           iam.get_iam_policy resource: topic_path(topic_name, options)
         end
@@ -341,6 +448,11 @@ module Google
           "#{project_path options}/snapshots/#{snapshot_name}"
         end
 
+        def schema_path schema_name, options = {}
+          return schema_name if schema_name.nil? || schema_name.to_s.include?("/")
+          "#{project_path options}/schemas/#{schema_name}"
+        end
+
         def inspect
           "#<#{self.class.name} (#{@project})>"
         end

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

@@ -15,6 +15,7 @@
 
 require "google/cloud/errors"
 require "google/cloud/pubsub/snapshot/list"
+require "google/cloud/pubsub/v1"
 
 module Google
   module Cloud

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

@@ -233,6 +233,78 @@ module Google
           @resource_name = nil
         end
 
+        ##
+        # The name of the schema that messages published should be validated against, if schema settings are configured
+        # for the topic. The value is a fully-qualified schema name in the form
+        # `projects/{project_id}/schemas/{schema_id}`. If present, {#message_encoding} should also be present. The value
+        # of this field will be `_deleted-schema_` if the schema has been deleted.
+        #
+        # Makes an API call to retrieve the schema settings when called on a reference object. See {#reference?}.
+        #
+        # @return [String, nil] The schema name, or `nil` if schema settings are not configured for the topic.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   topic.schema_name #=> "projects/my-project/schemas/my-schema"
+        #
+        def schema_name
+          ensure_grpc!
+          @grpc.schema_settings&.schema
+        end
+
+        ##
+        # The encoding of messages validated against the schema identified by {#schema_name}. If present, {#schema_name}
+        # should also be present. Values include:
+        #
+        # * `JSON` - JSON encoding.
+        # * `BINARY` - Binary encoding, as defined by the schema type. For some schema types, binary encoding may not be
+        #   available.
+        #
+        # Makes an API call to retrieve the schema settings when called on a reference object. See {#reference?}.
+        #
+        # @return [Symbol, nil] The schema encoding, or `nil` if schema settings are not configured for the topic.
+        #
+        # @example
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   topic = pubsub.topic "my-topic"
+        #
+        #   topic.message_encoding #=> :JSON
+        #
+        def message_encoding
+          ensure_grpc!
+          @grpc.schema_settings&.encoding
+        end
+
+        ##
+        # Checks if the encoding of messages in the schema settings is `BINARY`. See {#message_encoding}.
+        #
+        # Makes an API call to retrieve the schema settings when called on a reference object. See {#reference?}.
+        #
+        # @return [Boolean] `true` when `BINARY`, `false` if not `BINARY` or schema settings is not set.
+        #
+        def message_encoding_binary?
+          message_encoding.to_s.upcase == "BINARY"
+        end
+
+        ##
+        # Checks if the encoding of messages in the schema settings is `JSON`. See {#message_encoding}.
+        #
+        # Makes an API call to retrieve the schema settings when called on a reference object. See {#reference?}.
+        #
+        # @return [Boolean] `true` when `JSON`, `false` if not `JSON` or schema settings is not set.
+        #
+        def message_encoding_json?
+          message_encoding.to_s.upcase == "JSON"
+        end
+
         ##
         # Permanently deletes the topic.
         #

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module PubSub
-      VERSION = "2.4.0".freeze
+      VERSION = "2.5.0".freeze
     end
 
     Pubsub = PubSub unless const_defined? :Pubsub

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-pubsub
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.5.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-03-11 00:00:00.000000000 Z
+date: 2021-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -67,6 +67,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: avro
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
 - !ruby/object:Gem::Dependency
   name: google-style
   requirement: !ruby/object:Gem::Requirement
@@ -225,6 +239,8 @@ files:
 - lib/google/cloud/pubsub/publish_result.rb
 - lib/google/cloud/pubsub/received_message.rb
 - lib/google/cloud/pubsub/retry_policy.rb
+- lib/google/cloud/pubsub/schema.rb
+- lib/google/cloud/pubsub/schema/list.rb
 - lib/google/cloud/pubsub/service.rb
 - lib/google/cloud/pubsub/snapshot.rb
 - lib/google/cloud/pubsub/snapshot/list.rb