google-cloud-pubsub 0.26.0 → 2.6.1

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/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