discovery_v1 0.1.0

data/lib/discovery_v1/validation/load_schemas.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/inflector'
+
+module DiscoveryV1
+  module Validation
+    # Load the Google Discovery V1 API description for the Discovery V1 API
+    #
+    # @example
+    #   logger = Logger.new(STDOUT, :level => Logger::ERROR)
+    #   schemas = DiscoveryV1::Validation::LoadSchemas.new(logger:).call
+    #
+    # @api private
+    #
+    class LoadSchemas
+      # Loads schemas for the Discovery V1 API object from the Google Discovery V1 API
+      #
+      # By default, a nil logger is used. This means that nothing is logged.
+      #
+      # The schemas are only loaded once and cached.
+      #
+      # @example
+      #   schema_loader = DiscoveryV1::Validation::LoadSchemas.new
+      #
+      # @param rest_description [Google::Apis::DiscoveryV1::RestDescription]
+      #   the api description to load schemas from
+      # @param logger [Logger] the logger to use
+      #
+      def initialize(rest_description:, logger: Logger.new(nil))
+        @rest_description = rest_description
+        @logger = logger
+      end
+
+      # The Google Discovery V1 API description to load schemas from
+      #
+      # @example
+      #   rest_description = DiscoveryV1.discovery_service.get_rest_description('sheets', 'v4')
+      #   loader = DiscoveryV1::Validation::LoadSchemas.new(rest_description:)
+      #   loader.rest_description == rest_description # => true
+      #
+      # @return [Google::Apis::DiscoveryV1::RestDescription]
+      #
+      attr_reader :rest_description
+
+      # The logger to use internally for logging errors
+      #
+      # @example
+      #   logger = Logger.new(STDOUT, :level => Logger::INFO)
+      #   schema_loader = DiscoveryV1::Validation::LoadSchemas.new(logger)
+      #   schema_loader.logger == logger # => true
+      #
+      # @return [Logger]
+      #
+      attr_reader :logger
+
+      # A hash of schemas keyed by schema name loaded from the Google Discovery V1 API
+      #
+      # @example
+      #   DiscoveryV1.api_object_schemas #=> { 'PersonSchema' => { 'type' => 'object', ... } ... }
+      #
+      # @return [Hash<String, Object>] a hash of schemas keyed by schema name
+      #
+      def call
+        self.class.load_schemas_mutex.synchronize do
+          self.class.schemas(rest_description:) ||
+            self.class.memoize_schemas(rest_description:, schemas: load_api_schemas)
+        end
+      end
+
+      private
+
+      # A mutex used to synchronize access to the schemas so they are only loaded
+      # once
+      #
+      # @return [Thread::Mutex]
+      #
+      @load_schemas_mutex = Thread::Mutex.new
+
+      # Memoization cache that stores the schemas for each rest_description
+      #
+      # The cache is a hash where:
+      # * The key is the canonical name of the rest_description
+      # * The value is a hash of schemas keyed by schema name
+      #
+      # @return [Hash<String, Object] a hash of schemas keyed by schema name
+      #
+      # @api private
+      #
+      @schemas_cache = {}
+
+      class << self
+        # A mutex used to synchronize access to the schemas so they are only loaded once
+        #
+        # @return [Thread::Mutex]
+        #
+        # @api private
+        #
+        attr_reader :load_schemas_mutex
+
+        # The memoized schemas for the given rest_description or nil
+        #
+        # @param rest_description [Google::Apis::DiscoveryV1::RestDescription] the
+        #   rest_description to get the schemas for
+        #
+        # @return [Hash<String, Object>, nil] a hash of schemas keyed by schema name
+        #
+        # @api private
+        #
+        def schemas(rest_description:)
+          @schemas_cache[rest_description.canonical_name]
+        end
+
+        # Memoize the schemas for the given rest_description returning the given schemas
+        #
+        # @param rest_description [Google::Apis::DiscoveryV1::RestDescription] the
+        #   rest_description to memoize the schemas for
+        # @param schemas [Hash<String, Object>] a hash of schemas keyed by schema name
+        #
+        # @return [Hash<String, Object>] the given schemas
+        #
+        # @api private
+        #
+        def memoize_schemas(rest_description:, schemas:)
+          @schemas_cache[rest_description.canonical_name] = schemas
+        end
+
+        # Clear the memoization cache (intended for testing)
+        #
+        # @return [void]
+        #
+        # @api private
+        #
+        def clear_schemas_cache
+          @schemas_cache = {}
+        end
+      end
+
+      # Load the schemas from the Google Discovery V1 API
+      #
+      # @return [Hash<String, Object>] a hash of schemas keyed by schema name
+      #
+      # @api private
+      #
+      def load_api_schemas
+        source = "https://#{rest_description.name}.googleapis.com/$discovery/rest?version=#{rest_description.version}"
+        http_response = Net::HTTP.get_response(URI.parse(source))
+        raise_error(http_response) if http_response.code != '200'
+
+        data = http_response.body
+        JSON.parse(data)['schemas'].tap { |schemas| post_process_schemas(schemas) }
+      end
+
+      # Log an error and raise a RuntimeError based on the HTTP response code
+      # @param http_response [Net::HTTPResponse] the HTTP response
+      # @return [void]
+      # @raise [RuntimeError]
+      # @api private
+      def raise_error(http_response)
+        message = "HTTP Error '#{http_response.code}' loading schemas from '#{http_response.uri}'"
+        logger.error(message)
+        raise message
+      end
+
+      REF_KEY = '$ref'
+
+      # A visitor for the schema object tree that fixes up the tree as it goes
+      # @return [void]
+      # @api private
+      def schema_visitor(path:, object:)
+        return unless object.is_a? Hash
+
+        convert_schema_names_to_snake_case(path, object)
+        convert_schema_ids_to_snake_case(path, object)
+        add_unevaluated_properties(path, object)
+        convert_property_names_to_snake_case(path, object)
+        convert_ref_values_to_snake_case(path, object)
+      end
+
+      # Convert schema names to snake case
+      # @return [void]
+      # @api private
+      def convert_schema_names_to_snake_case(path, object)
+        object.transform_keys!(&:underscore) if path.empty?
+      end
+
+      # Convert schema IDs to snake case
+      # @return [void]
+      # @api private
+      def convert_schema_ids_to_snake_case(path, object)
+        object['id'] = object['id'].underscore if object.key?('id') && path.size == 1
+      end
+
+      # Add 'unevaluatedProperties: false' to all schemas
+      # @return [void]
+      # @api private
+      def add_unevaluated_properties(path, object)
+        object['unevaluatedProperties'] = false if path.size == 1
+      end
+
+      # Convert object property names to snake case
+      # @return [void]
+      # @api private
+      def convert_property_names_to_snake_case(path, object)
+        object.transform_keys!(&:underscore) if path[-1] == 'properties'
+      end
+
+      # Convert reference values to snake case
+      # @return [void]
+      # @api private
+      def convert_ref_values_to_snake_case(path, object)
+        object[REF_KEY] = object[REF_KEY].underscore if object.key?(REF_KEY) && path[-1] != 'properties'
+      end
+
+      # Traverse the schema object tree and apply the schema visitor to each node
+      # @return [void]
+      # @api private
+      def post_process_schemas(schemas)
+        DiscoveryV1::Validation::TraverseObjectTree.call(
+          object: schemas, visitor: ->(path:, object:) { schema_visitor(path:, object:) }
+        )
+      end
+    end
+  end
+end

data/lib/discovery_v1/validation/resolve_schema_ref.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module DiscoveryV1
+  module Validation
+    # Resolve a JSON schema reference to a Google Discovery V1 API schema
+    #
+    # This class uses the Google Discovery V1 API to get the schemas. Any schema reference
+    # in the form `{ "$ref": "schema_name" }` will be resolved by looking up the schema
+    # name in the Google Discovery V1 API and returning the schema object (as a Hash).
+    #
+    # This means that `{ "$ref": "cell_data" }` is resolved by returning
+    # `DiscoveryV1::Validation::LoadSchemas.new(logger:).call['cell_data']`.
+    #
+    # An RuntimeError is raised if `DiscoveryV1::Validation::LoadSchemas.new.call`
+    # does not have a key matching the schema name.
+    #
+    # @example
+    #   logger = Logger.new(STDOUT, level: Logger::INFO)
+    #   ref_resolver = DiscoveryV1::Validation::ResolveSchemaRef.new(logger:)
+    #   people_schema = { 'type' => 'array', 'items' => { '$ref' => 'person' } }
+    #   json_validator = JSONSchemer.schema(people_schema, ref_resolver:)
+    #   people_json = [{ 'name' => { 'first' => 'John', 'last' => 'Doe' } }]
+    #
+    #   # Trying to validate people_json using json_validator as follows:
+    #
+    #   json_validator.validate(people_json)
+    #
+    #   # will try to load the referenced schema for 'person'. json_validator will
+    #   # do this by calling `ref_resolver.call(URI.parse('json-schemer://schema/person'))`
+    #
+    # @api private
+    #
+    class ResolveSchemaRef
+      # Create a new schema resolver
+      #
+      # @param rest_description [Google::Apis::DiscoveryV1::RestDescription] the api description to load schemas from
+      # @param logger [Logger] the logger to use
+      #
+      # @api private
+      #
+      def initialize(rest_description:, logger: Logger.new(nil))
+        @rest_description = rest_description
+        @logger = logger
+      end
+
+      # The Google Discovery V1 API description to load schemas from
+      #
+      # @example
+      #   rest_description = DiscoveryV1.discovery_service.get_rest_description('sheets', 'v4')
+      #   resolver = DiscoveryV1::Validation::ResolveSchemaRef.new(rest_description:)
+      #   resolver.rest_description == rest_description # => true
+      #
+      # @return [Google::Apis::DiscoveryV1::RestDescription]
+      #
+      attr_reader :rest_description
+
+      # The logger to use internally
+      #
+      # Currently, only debug messages are logged.
+      #
+      # @return [Logger]
+      #
+      # @api private
+      #
+      attr_reader :logger
+
+      # Resolve a JSON schema reference
+      #
+      # @param ref [URI] the reference to resolve usually in the form "json-schemer://schema/[name]"
+      #
+      # @return [Hash] the schema object as a hash
+      #
+      # @api private
+      #
+      def call(ref)
+        schema_name = ref.path[1..]
+        logger.debug { "Reading schema #{schema_name}" }
+        schemas = DiscoveryV1::Validation::LoadSchemas.new(rest_description:, logger:).call
+        schemas[schema_name].tap do |schema_object|
+          raise "Schema for #{ref} not found" unless schema_object
+        end
+      end
+    end
+  end
+end

data/lib/discovery_v1/validation/traverse_object_tree.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module DiscoveryV1
+  module Validation
+    # Visit all objects in arbitrarily nested object tree of hashes and/or arrays
+    #
+    # @api public
+    #
+    class TraverseObjectTree
+      # Visit all objects in arbitrarily nested object tree of hashes and/or arrays
+      #
+      # For each object, the visitor is called with the path to the object and the object
+      # itself.
+      #
+      # @example
+      #   # In the examples below assume the elided code is the following:
+      #   visitor = -> (path:, object:) { puts "path: #{path}, object: #{obj}" }
+      #   DiscoveryV1::Validation::TraverseObjectTree.call(object:, visitor:)
+      #
+      # @example Given a simple object (not very exciting)
+      #   object = 1
+      #   ...
+      #   #=> path: [], object: 1
+      #
+      # @example Given an array
+      #   object = [1, 2, 3]
+      #   ...
+      #   #=> path: [], object: [1, 2, 3]
+      #   #=> path: [0], object: 1
+      #   #=> path: [1], object: 2
+      #   #=> path: [2], object: 3
+      #
+      # @example Given a hash
+      #   object = { name: 'James', age: 42 }
+      #   ...
+      #   #=> path: [], object: { name: 'James', age: 42 }
+      #   #=> path: [:name], object: James
+      #   #=> path: [:age], object: 42
+      #
+      # @example Given an array of hashes
+      #   object = [{ name: 'James', age: 42 }, { name: 'Jane', age: 43 }]
+      #   ...
+      #   #=> path: [], object: [{ name: 'James', age: 42 }, { name: 'Jane', age: 43 }]
+      #   #=> path: [0], object: { name: 'James', age: 42 }
+      #   #=> path: [0, :name], object: James
+      #   #=> path: [0, :age], object: 42
+      #   #=> path: [1], object: { name: 'Jane', age: 43 }
+      #   #=> path: [1, :name], object: Jane
+      #   #=> path: [1, :age], object: 43
+      #
+      # @example Given a hash of hashes
+      #   object = { person1: { name: 'James', age: 42 }, person2: { name: 'Jane', age: 43 } }
+      #   ...
+      #   #=> path: [], object: { person1: { name: 'James', age: 42 }, person2: { name: 'Jane', age: 43 } }
+      #   #=> path: [:person1], object: { name: 'James', age: 42 }
+      #   #=> path: [:person1, :name], object: James
+      #   #=> path: [:person1, :age], object: 42
+      #   #=> path: [:person2], object: { name: 'Jane', age: 43 }
+      #   #=> path: [:person2, :name], object: Jane
+      #   #=> path: [:person2, :age], object: 43
+      #
+      # @param path [Array] the path to the object
+      # @param object [Object] the object to visit
+      # @param visitor [#call] the visitor to call for each object
+      #
+      # @return [void]
+      #
+      # @api public
+      #
+      def self.call(object:, visitor:, path: [])
+        visitor&.call(path:, object:)
+        if object.is_a? Hash
+          object.each { |k, obj| call(path: (path + [k]), object: obj, visitor:) }
+        elsif object.is_a? Array
+          object.each_with_index { |obj, k| call(path: (path + [k]), object: obj, visitor:) }
+        end
+      end
+    end
+  end
+end

data/lib/discovery_v1/validation/validate_object.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'json_schemer'
+
+module DiscoveryV1
+  module Validation
+    # Validate objects against a Google Discovery V1 API request object schema
+    #
+    # @api public
+    #
+    class ValidateObject
+      # Create a new api object validator
+      #
+      # By default, a nil logger is used. This means that no messages are logged.
+      #
+      # @example
+      #   validator = DiscoveryV1::Validation::ValidateObject.new
+      #
+      # @param logger [Logger] the logger to use
+      #
+      def initialize(rest_description:, logger: Logger.new(nil))
+        @rest_description = rest_description
+        @logger = logger
+      end
+
+      # The Google Discovery V1 API description containing schemas to use for validation
+      #
+      # @example
+      #   rest_description = DiscoveryV1.discovery_service.get_rest_description('sheets', 'v4')
+      #   validator = DiscoveryV1::Validation::ValidateObject.new(rest_description:)
+      #   validator.rest_description == rest_description # => true
+      #
+      # @return [Google::Apis::DiscoveryV1::RestDescription]
+      #
+      attr_reader :rest_description
+
+      # The logger to use internally
+      #
+      # Validation errors are logged at the error level. Other messages are logged
+      # at the debug level.
+      #
+      # @example
+      #   logger = Logger.new(STDOUT, :level => Logger::INFO)
+      #   validator = DiscoveryV1::Validation::ValidateObject.new(logger)
+      #   validator.logger == logger # => true
+      #   validator.logger.debug { "Debug message" }
+      #
+      # @return [Logger]
+      #
+      attr_reader :logger
+
+      # Validate the object using the JSON schema named schema_name
+      #
+      # @example
+      #   schema_name = 'batch_update_spreadsheet_request'
+      #   object = { 'requests' => [] }
+      #   validator = DiscoveryV1::Validation::ValidateObject.new
+      #   validator.call(schema_name:, object:)
+      #
+      # @param schema_name [String] the name of the schema to validate against
+      # @param object [Object] the object to validate
+      #
+      # @raise [RuntimeError] if the object does not conform to the schema
+      #
+      # @return [void]
+      #
+      def call(schema_name:, object:)
+        logger.debug { "Validating #{object} against #{schema_name}" }
+
+        schema = { '$ref' => schema_name }
+        schemer = JSONSchemer.schema(schema, ref_resolver:)
+        errors = schemer.validate(object)
+        raise_error!(schema_name, object, errors) if errors.any?
+
+        logger.debug { "Object #{object} conforms to #{schema_name}" }
+      end
+
+      private
+
+      # The resolver to use to resolve JSON schema references
+      # @return [ResolveSchemaRef]
+      # @api private
+      def ref_resolver
+        @ref_resolver ||= DiscoveryV1::Validation::ResolveSchemaRef.new(rest_description:, logger:)
+      end
+
+      # Raise an error when the object does not conform to the schema
+      # @return [void]
+      # @raise [RuntimeError]
+      # @api private
+      def raise_error!(schema_name, _object, errors)
+        error = errors.first['error']
+        error_message = "Object does not conform to #{schema_name}: #{error}"
+        logger.error(error_message)
+        raise error_message
+      end
+    end
+  end
+end

data/lib/discovery_v1/validation.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module DiscoveryV1
+  # Validate API Objects against the Google Discovery V1 API
+  #
+  # @example
+  #   discovery_service = DiscoveryV1.discovery_service
+  #   rest_description = discovery_service.get_rest_description('sheets', 'v4')
+  #   schema_name = 'batch_update_spreadsheet_request'
+  #   object = { 'requests' => [] }
+  #   DiscoveryV1::Validation::ValidateObject.new(rest_description:).call(schema_name:, object:)
+  #
+  # @api public
+  #
+  module Validation; end
+end
+
+require_relative 'validation/load_schemas'
+require_relative 'validation/resolve_schema_ref'
+require_relative 'validation/traverse_object_tree'
+require_relative 'validation/validate_object'

data/lib/discovery_v1/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module DiscoveryV1
+  # The version of this gem
+  VERSION = '0.1.0'
+end

data/lib/discovery_v1.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'google/apis/discovery_v1'
+
+require_relative 'discovery_v1/version'
+require_relative 'discovery_v1/validation'
+
+# Unofficial helpers for the Google Discovery V1 API
+#
+# @api public
+#
+module DiscoveryV1
+  class << self
+    # Create a new Google::Apis::DiscoveryV1::DiscoveryService object
+    #
+    # A credential is not needed to use the DiscoveryService.
+    #
+    # @example
+    #   DiscoveryV1.discovery_service
+    #
+    # @return [Google::Apis::DiscoveryV1::DiscoveryService] a new DiscoveryService instance
+    #
+    def discovery_service
+      Google::Apis::DiscoveryV1::DiscoveryService.new
+    end
+
+    # @!group Validation
+
+    # Validate the object using the named JSON schema
+    #
+    # The JSON schemas are loaded from the Google Disocvery API. The schemas names are
+    # returned by `DiscoveryV1.api_object_schema_names`.
+    #
+    # @example
+    #   schema_name = 'batch_update_spreadsheet_request'
+    #   object = { 'requests' => [] }
+    #   DiscoveryV1.validate_api_object(schema_name:, object:)
+    #
+    # @param rest_description [Google::Apis::DiscoveryV1::RestDescription] the Google Discovery V1 API rest description
+    # @param schema_name [String] the name of the schema to validate against
+    # @param object [Object] the object to validate
+    # @param logger [Logger] the logger to use for logging error, info, and debug message
+    #
+    # @raise [RuntimeError] if the object does not conform to the schema
+    #
+    # @return [void]
+    #
+    def validate_object(rest_description:, schema_name:, object:, logger: Logger.new(nil))
+      DiscoveryV1::Validation::ValidateObject.new(rest_description:, logger:).call(schema_name:, object:)
+    end
+
+    # List the names of the schemas available to use in the Google Discovery V1 API
+    #
+    # @example List the name of the schemas available
+    #   rest_description = DiscoveryV1.discovery_service.get_rest_api('sheets', 'v4')
+    #   DiscoveryV1.api_object_schema_names #=> ["add_banding_request", "add_banding_response", ...]
+    #
+    # @param rest_description [Google::Apis::DiscoveryV1::RestDescription] the Google Discovery V1 API rest description
+    # @param logger [Logger] the logger to use for logging error, info, and debug message
+    #
+    # @return [Array<String>] the names of the schemas available
+    #
+    def object_schema_names(rest_description:, logger: Logger.new(nil))
+      DiscoveryV1::Validation::LoadSchemas.new(rest_description:, logger:).call.keys.sort
+    end
+
+    # @!endgroup
+  end
+end

data/sig/discovery_v1.rbs

@@ -0,0 +1,4 @@
+module DiscoveryV1
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end