sheets_v4 0.3.0 → 0.5.0

data/lib/sheets_v4/validate_api_objects/load_schemas.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module SheetsV4
+  module ValidateApiObjects
+    # Load the Google Discovery API description for the Sheets V4 API
+    #
+    # @example
+    #   logger = Logger.new(STDOUT, :level => Logger::ERROR)
+    #   schemas = SheetsV4::ValidateApiObjects::LoadSchemas.new(logger:).call
+    #
+    # @api private
+    #
+    class LoadSchemas
+      # Loads schemas for the Sheets V4 API object from the Google Discovery 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 = SheetsV4::ValidateApiObjects::LoadSchemas.new
+      #
+      # @param logger [Logger] the logger to use
+      #
+      def initialize(logger: Logger.new(nil))
+        @logger = logger
+      end
+
+      # The logger to use internally for logging errors
+      #
+      # @example
+      #   logger = Logger.new(STDOUT, :level => Logger::INFO)
+      #   validator = SheetsV4::ValidateApiObjects::LoadSchemas.new(logger)
+      #   validator.logger == logger # => true
+      #
+      # @return [Logger]
+      #
+      attr_reader :logger
+
+      # A hash of schemas keyed by the schema name loaded from the Google Discovery API
+      #
+      # @example
+      #   SheetsV4.api_object_schemas #=> { 'PersonSchema' => { 'type' => 'object', ... } ... }
+      #
+      # @return [Hash<String, Object>] a hash of schemas keyed by schema name
+      #
+      def call
+        self.class.schema_load_semaphore.synchronize { @call ||= load_api_object_schemas }
+      end
+
+      private
+
+      # Validate
+      # A mutex used to synchronize access to the schemas so they are only loaded
+      # once.
+      #
+      @schema_load_semaphore = Thread::Mutex.new
+
+      class << self
+        # A mutex used to synchronize access to the schemas so they are only loaded once
+        #
+        # @return [Thread::Mutex]
+        #
+        # @api private
+        #
+        attr_reader :schema_load_semaphore
+      end
+
+      # Load the schemas from the Google Discovery API
+      #
+      # @return [Hash<String, Object>] a hash of schemas keyed by schema name
+      #
+      # @api private
+      #
+      def load_api_object_schemas
+        source = 'https://sheets.googleapis.com/$discovery/rest?version=v4'
+        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]
+      # @raises [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)
+      end
+
+      # Traverse the schema object tree and apply the schema visitor to each node
+      # @return [void]
+      # @api private
+      def post_process_schemas(schemas)
+        SheetsV4::ValidateApiObjects::TraverseObjectTree.call(
+          object: schemas, visitor: ->(path:, object:) { schema_visitor(path:, object:) }
+        )
+      end
+    end
+  end
+end

data/lib/sheets_v4/validate_api_objects/resolve_schema_ref.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SheetsV4
+  module ValidateApiObjects
+    # Resolve a JSON schema reference to a Google Sheets API schema
+    #
+    # This class uses the Google Discovery 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 API and returning the schema object (as a Hash).
+    #
+    # This means that `{ "$ref": "cell_data" }` is resolved by returning
+    # `SheetsV4::ValidateApiObjects::LoadSchemas.new(logger:).call['cell_data']`.
+    #
+    # An RuntimeError is raised if `SheetsV4::ValidateApiObjects::LoadSchemas.new.call`
+    # does not have a key matching the schema name.
+    #
+    # @example
+    #   logger = Logger.new(STDOUT, level: Logger::INFO)
+    #   ref_resolver = SheetsV4::ValidateApiObjects::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 logger [Logger] the logger to use
+      #
+      # @api private
+      #
+      def initialize(logger: Logger.new(nil))
+        @logger = logger
+      end
+
+      # 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 = SheetsV4::ValidateApiObjects::LoadSchemas.new(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/sheets_v4/validate_api_objects/traverse_object_tree.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module SheetsV4
+  module ValidateApiObjects
+    # 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.
+      #
+      # In the examples below assume the elided code is the following:
+      #
+      # ```Ruby
+      # visitor = -> (path:, object:) { puts "path: #{path}, object: #{obj}" }
+      # SheetsV4::ValidateApiObjects::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/sheets_v4/validate_api_objects/validate.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'active_support/inflector'
+require 'json_schemer'
+
+module SheetsV4
+  module ValidateApiObjects
+    # Validate objects against a Google Sheets API request object schema
+    #
+    # @api public
+    #
+    class Validate
+      # Create a new validator
+      #
+      # By default, a nil logger is used. This means that no messages are logged.
+      #
+      # @example
+      #   validator = SheetsV4::ValidateApiObjects::Validator.new
+      #
+      # @param logger [Logger] the logger to use
+      #
+      def initialize(logger: Logger.new(nil))
+        @logger = logger
+      end
+
+      # 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 = SheetsV4::ValidateApiObjects::Validator.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 = SheetsV4::ValidateApiObjects::Validator.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 ||= SheetsV4::ValidateApiObjects::ResolveSchemaRef.new(logger:)
+
+      # 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 #{object} does not conform to #{schema_name}: #{error}"
+        logger.error(error_message)
+        raise error_message
+      end
+    end
+  end
+end

data/lib/sheets_v4/validate_api_objects.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SheetsV4
+  # Validate API Objects against the Google Discovery API
+  #
+  # @example
+  #   logger = Logger.new(STDOUT, :level => Logger::ERROR)
+  #   schema_name = 'batch_update_spreadsheet_request'
+  #   object = { 'requests' => [] }
+  #   SheetsV4::ValidateApiObjects::Validator.new(logger:).call(schema_name:, object:)
+  #
+  # @api public
+  #
+  module ValidateApiObjects; end
+end
+
+require_relative 'validate_api_objects/load_schemas'
+require_relative 'validate_api_objects/resolve_schema_ref'
+require_relative 'validate_api_objects/traverse_object_tree'
+require_relative 'validate_api_objects/validate'

data/lib/sheets_v4/version.rb

@@ -2,5 +2,5 @@
 
 module SheetsV4
   # The version of this gem
-  VERSION = '0.3.0'
+  VERSION = '0.5.0'
 end